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PREFACE 


Intercomm is a state-of-the-art teleprocessing monitor system 
executing on the IBM System/370 family of computers and operating under 
the control of IBM Operating Systems (MVS/370, XA, ESA). Intercomm 
monitors the transmission of messages to and from terminals, concurrent 
message processing, centralized access to I/O files, and the routine 
utility operations of editing input messages and formatting output 
messages, as required. 


The Assembler Language Programmers Guide explains the 
organization of Intercomm from the application programmer's point of 
view and illustrates the procedures for creating Assembler Language 
application programs and integrating them into the Intercomm 
environment. 


Syntax used in describing the coding of JCL or application 
program statements is: . 


® { } A pair of braces indicates the presence of a choice: 
code elements contained within the braces represent 
alternatives, one of which must be chosen. The braces 


are not to be coded. 


@ [ ] A pair of brackets indicates an optional parameter which 
may be omitted depending on access ‘requirements as 
described in the accompanying text. The brackets are not 
to be coded. 


e A parameter consisting partially or solely of lower case 
letters represents the generic (Intercomm) name of the value. 
The programmer must substitute the actual name used for 
defining the data area within the specific program. ’ 


As a prerequisite to this manual, it is assumed ‘that the user is 
familiar with the Intercomm CGoncéepts’ and Facilities “Manual. The 
following manuals describe in further detail facilities “referericed in 
this manual: 4 Cares 


e Basic System Macros . 


® Message Mapping Utilities 

® Utilities Users Guide 

® Store/Fetch Facility Users Guide 

e Dynamic Data Queuing Facility Be, ee nee 

e Page Facility : Lge 
e Operating Reference Manual: "Message Managenient" 


"File Managemefit" 


INTERCOMM PUBLICATIONS ) 


GENERAL INFORMATION MANUALS FEATURE IMPLEMENTATION MANUALS 
Concepts and Facilities Autogen Facility 
Planning Guide ASMF Users Guide 


DBMS Users Guide 
APPLICATION PROGRAMMERS MANUALS Data Entry Installation Guide 


Assembler Language Programmers Guide Data Entry Terminal Operators Guide 


COBOL Programmers Guide Dynamic Data Queuing Facility 
PL/1 Programmers Guide Dynamic File Allocation 


Extended Security System 


SYSTEM PROGRAMMERS MANUALS File Recovery Users Guide 
Basic System Macros Generalized Front End Facility 
BTAM Terminal Support Cuide Message Mapping Utilities 
Installation Guide Model System Generator Jo 
Messages and Codes Multiregion Support Facility 
Operating Reference Manual Page Facility 
System Control Commands Store/Fetch Facility 


SNA Terminal Support Guide 


CUSTOMER INFORMATION MANUALS TCAM Support Users Guide 
Customer Education Course Gatalog Utilities Users Guide 


Technical Information Bulletins 


User Contributed Program Description EXTERNAL FEATURES MANUALS 


SNA LU6.2 Support Guide 
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Chapter l 


INTRODUCTORY CONCEPTS OF ON-LINE SYSTEMS 


1.1 INTRODUCTION 
The objective of most on-line systems is to reduce the time 
factor from source of input data to the results of data processing. 
Typical on-line systems applications in the business environment are: 
e Data Collection 
Transactions may be edited partially on receipt, batch totals 
may be transmitted and verified, but the bulk of processing 
of the collected data takes place in the batch mode off-line. 


e Ingquir date Systems 


Transactions are processed immediately to retrieve and/or 
update information in an on-line data base. 


e Message Switching 


Transactions consist of administrative data to be rerouted to 
other terminals in the system. 


On-line systems are characterized by a mode of operation which is 


nonscheduled and transaction-oriented. An operator at a terminal 
remote from the data processing center enters a transaction (unit of 
work) by transmitting a message over communication facilities. Each 


individual transaction is processed immediately, as opposed to batch 
systems, where transactions are accumulated for processing on a 
periodic basis (monthly, daily, etc.). 


Online systems are designed to satisfy a response time 
requirement which is the elapsed time between a request for processing 
of an input message from a terminal to receipt of an acknowledgement, 
or response to that input message (completion of a transaction). 


1.2 THE ON-LINE SYSTEM ENVIRONMENT 


Typical on-line message processing application programs operate 
on one transaction at a time as they come in from terminals. 
Application programs are usually designed to process only one type of 
transaction, and the whole environment can be said to be transaction 


oriented. Input messages can be processed as received, in any order, 
and the files to be referenced should not be read from beginning to end 
for each transaction. Instead, the records in files are accessed 


directly, either through a specific key or some form of cross-reference 
look-up. 
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A few applications might require some sequential or list 
processing of a file, and while this is possible, message processing 
times for such applications would tend to be high. 


Figure ). shows a computer system schematic depicting a memory 
layout with an on-line system such as Intercomm, operating in a region 
or address space as a job under an operating system such as IBM's MVS. 
The on-line system has its own Transaction Monitor which schedules the 
activation of transaction processing according to the varying demands 
in message traffic. 


COMPUTER PROCESSOR 


TRANSACTION FILE 
DEVICES OPERATING SYSTEM DEVICES 


ON-LINE 
SYSTEM 
MONITOR 


RETRIEV 
PROCESS 
f REPLY / 


REPLY 


RETRIEVE 
PROCESS 


Figure 1. On-line Transaction Processing in a 
Multiprogramming Environment 
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The transaction processing programs do not conduct input or 
output operations with the terminals. This function is provided by the 
on-line system, which reads input messages from terminals and saves 
them (queues them) until the appropriate processing program can be 
activated (scheduled). The message is then retrieved from the queue 
and passed directly to the processing program by the Monitor. The 
processing program then requests the Monitor to queue its output 
response message, and the Monitor handles the terminal output function. 


13 BATCH ENVIRONMENT VS. ON-LINE ENVIRONMENT 


The classical batch processing system flow of 
input/process/output can be expanded to include message queuing and 


retrieving in the on-line environment. However, the typical on-line 
application program need only be concerned with actual transaction 
processing, because the on-line system does the rest. Figure 2 


summarizes some of the differences between batch and on-line 
environments. 
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Batch Online 


eS 


Scheduled input Unscheduled input 
Single-application job Multiple-application job 
Delayed processing of transactions |Immediate processing of individual 
in batches by type transactions by type 
Transaction input, processing, and |Terminal input/output events are 
output controlled by processing asynchronous to the processing 
program logic program 

Figure 2. Differences Between Batch and On-line Environments 
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1.4 SINGLE-THREAD VS. MULTITHREAD PROCESSING 


In the on-line environment, the logical path of a program in 
execution is called a thread. A single-thread system processes one 
message at a time. However, in a multiple application environment, 
message volume is such that all message traffic could not be adequately 
serviced in a single-thread mode. Large queues (waiting lines) tend to 
develop because messages arrive faster than they can be processed. To 
‘ alleviate this problem and improve system throughput, the delay time in 
the processing of one message waiting for an I/O operation may be used 
for simultaneously processing another message. In this way, several 
message processing logic paths, or threads, may be active at once. 
This is referred to as multithreading. 


Multithreading is coordinated by the Transaction Monitor, and, 
depending on message traffic, can occur between two or more programs or 
within a single program. 


To illustrate this, let us assume that we have two transaction 
processing programs, A and B, and that three messages have arrived for 
processing; two A-type transactions and one B-type transaction. 
Programs A and B both require access to records in a file, affording an 
opportunity for some processing overlap or multithreading. 
Multithreading would occur between programs A and B if while program A 
is waiting for file retrieval, program B is activated by the Monitor to 
carry out its message processing. However, if program A were 
reentrant, that is, written in such a way that it could handle more 
than one thread at a time, then multithreading could also occur within 
program A. This means that while reentrant program A is waiting for a 
file retrieval for the processing of one message, it may be activated 
again to carry out the parallel processing of a second, or nth, 
message. Figure 3 illustrates these concepts. 
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1.5 PROGRAM FUNCTIONS IN THE ON-LINE ENVIRONMENT 


An on-line system consists of programs to serve four different 
functions: 


e Line Control and Terminal Control 


-- Servicing input requests from the various terminal types 
including transmission error recovery 


-- Directing output to the various terminal types including 
transmission error recovery 


-- Intercepting and storing messages to non-operational 
devices, and retrieval of messages when devices become 


operational 


-- Translation of messages to and from terminal transmission 
code and EBCDIC code for processing 


e Message Processing Control 


-- Queuing new input messages until the associated message 
processing program is scheduled for execution 


-- Scheduling message processing programs to obtain best 
system throughput for message traffic 


-- Gontrolling multithread operation for concurrent 
processing of several messages 


-- Centralizing data file accesses to eliminate redundant 


operations and provide exclusive control over records 
during file updates 


® Systems Operation Control 
-- Security checking functions to restrict certain 
transactions to specific operators and/or terminals, and 
to prevent access to unauthorized functions/files. 


-- Logging (journaling) of all message traffic 


-- Checkpointing, Message Restart, File Recovery and 
Backout-On-The-Fly (dynamic file backout) facilities 


-- Cancellation of message processing programs when a 
program check or program loop occurs 


-- Collect and display system statistics 


-- Display and modify system status 
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e Message (Transaction) Processin 


-- Editing text data from terminal input, including format 
conversion and content editing of individual fields 


-- Retrieval and updating of data from on-line files 
-- Preparation of response (output) messages to terminals 


-- Queuing of response messages for output to terminals 


Le So1. Monitor Control Functions 
The Intercomm System provides complete facilities for: 
@ Line control and terminal control 
e Message processing control 


@ Systems operation control 


L542 Application Processing Functions 


Transaction processing logic lies within the coding domain of the 


application programmer. Intercomm provides the following message and 
file handling support: 


e Format conversion and editing of input fields 
e Centralized control of data files 


e Format conversion and placement of constant and variable 
information in response messages and terminal displays 


e Queuing of messages (for the same or another terminal, or 
another application) 


The installation-dependent application logic functions then need 
include only the following: 


e Content editing of individual input message fields 
e Retrieval and updating of data from on-line files 


@ Selection of individual fields for the output message(s) 
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MESSAGE PROCESSING AND CONTROL UNDER INTERCOMM 


2.1 THE INTERCOMM ENVIRONMENT 


Intercomm operates under MVS as a job in a region or address 
space. The job is loaded at the beginning of on-line operations and 
continues to operate until the terminal network is closed down. 
Intercomm contains many system programs and application subsystems. 
Intercomm system programs include the Monitor and other subprograms to 
handle such things as terminal and peripheral I/O operations. 
Subsystems are message processing application programs activated by the 


monitor. The term "subsystem" includes both application-oriented 
message processing programs written by users and Intercomm system 
command processing and utility programs. The Intercomm region contains 


the execution module itself plus dynamically allocated storage or work 
space, as illustrated in Figure 4. 


TO PERIPHERAL 
ON-LINE DEVICES 
TERMINALS COMPUTER 


OPERATING SYSTEM 
REGIONS 
SYSTEM 
PROGRAMS 


MESSAGE 
PROCESSING 
SUBSYSTEMS 


=SamOAWDMHBAH 


Figure 4. The Intercomm Environment 
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The system programs are time- or event-driven; the subsystems are 
message-driven. The Intercomm Monitor calls system programs to handle 
events and exceptional conditions as they occur, for example, terminal 
and peripheral I/O interrupts, time-dependent processing, excessive 
message traffic, and system operator commands. 


A subsystem, on the other hand, is called by the system monitor 
when there are messages queued for it and it has been scheduled for 
- execution. Subsystems, while executing, can use the IBM CALL macro to 
call user subroutines or to call system programs to perform services, 
such as accessing data files and queuing messages for output or for 
additional processing by other subsystems. Figure 5 shows that called 
system programs and user subroutines will always return to the calling 
subsystem (or subroutine), just as the subsystem itself, executing as a 
subroutine of Intercomm, must always return to the system monitor that 
originally activated it. 


SYSTEM PROGRAMS TRANSACTION SUBSYSTEMS 


MONITOR PROGRAM AA SYBSYSTEM 
CALL SUBAA ENTRY AA AA 


CALL SYSX 
PROGRAM AB 


CALL AC 


SUBSYSTEM 
nn 


Figure 5. Intercomm Control Sequence 
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2:2 SYSTEM COMPONENTS 


On-line system component programs are often categorized as 
resident or nonresident, system or user, but typical on-line 
terminology also distinguishes between Front End and Back End system 
components. 


2.2.1 Front End 


The Front End communicates with and monitors all terminals in the 
network, It receives and sends messages, checks validity, performs 
security checking if specified, and accomplishes appropriate code 
translation. The Front End communicates with the Intercomm message 
processing Back End via input message queuing and output message 
dequeuing routines. Although Intercomm has its own VTAM Front End, it 
can also interface with other software Front Ends such as TCAM and 
BTAM. 


2.2.2 Back End 


The Back End accomplishes all message processing control, system 
operation control, and processing of individual messages. Te is, 
essentially, the "director" of the entire on-line system operation. 


The Front End and the Monitor portion of the Back End are always 
resident, whereas message processing subsystems can be any combination 
of resident and loadable. (See Figure 6.) The decision to make a 
message processing subsystem permanently resident, or loadable, is 
based upon the trade-offs between response time, frequency of use, and 
total system core storage requirements. 


seal 
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2.3 SYSTEM PROGRAMS 


Intercomm system programs are written in Assembler language and 
include the Monitor, File Handler, high-level language interface 
routines to maintain reentrancy, and message processing service 
routines, 


The Monitor interfaces with the Front End via message queues and 


controls the processing of messages by subsystems. It is essentially a 
traffic director, analyzing message traffic and scheduling subsystems 
based upon traffic volume and priority criteria. The Monitor has four 


key components: 


e The TP queuing interface, which communicates with the Front 
End to dequeue input messages or to queue output messages 
created by subsystems. 


e The Subsystem Controller, which schedules, loads and 
activates the application subsystems, and performs clean up 
processing when the subsystem returns. 


e The Dispatcher, which controls the execution of all events in 
the system to accomplish multithreading. 


e The Resource Manager, which allocates/deallocates and 
controls dynamic resources (such as core storage) used by 
system and application programs. 


The File Handler is the central Intercomm routine where all 
peripheral I/O service for data files is controlled. The File Handler 
issues OPENs, CLOSEs, GETs, PUTs, READs, and WRITEs via the operating 
system data management facility. Subsystems merely call an appropriate 


File Handler routine. Therefore, all access methods supported by 
Intercomm are available to any subsystem program, regardless of the 
programming language used. The File Handler maintains a single set of 


control blocks for each file defined to it via standard Job Control 
Language Data Definition statements, and all programs share this one 
set of control blocks. Intercomm can control overlapping of peripheral 
I/O processing, as well as provide standardized error analysis. A file 
is usually opened only once during an on-line session: at the time the 
first I/0 is requested. Since files can be accessed concurrently by 
different subsystems, an exclusive control feature is provided to 
eliminate difficulties arising when two or more subsystems (or 
subsystem threads) attempt to update the same record at the same time. 


Language interface routines are described in Chapter 3. 
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BACK- END 
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Figure 6. Intercomm System Components 
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The basic message processing service routines are: 


@ FESEND--which passes an output message to the Front End for 
transmission to a terminal. 


e LOGPUT--which copies a message onto the system log whenever 
called by a system program or subsystem. 


e MESSAGE COLLECTION--which handles the queuing and dequeuing 
of all messages destined for subsystems. 


Intercomm provides service routines to convert terminal-dependent 
input messages to a terminal-independent form for application 


processing. This transformation includes removal of terminal-dependent 
control characters and conversion of numeric data fields to 
computational or binary form, if required. Similarly, for output 
messages, service routines provide transformation from 
terminal-independent results of application subsystem processing to 
terminal-dependent messages for transmission. This includes insertion 


of terminal-dependent control characters, conversion of data fields to 
character format, if required, and inclusion of title information, if 
specified. Each of these routines function via user-specified 
descriptions (tables) of input and output message formats. These 
service routines are: 


e Message Mapping Utilities 


This is a set of service routines called by an application 
program to perform the device-dependent transformations 
specified by the user for both input and output messages. 
Validity checking, conversion, justification and 
padding/truncation of data fields is also performed. This 
utility also executes output message disposition 
(queuing/spooling), if requested. 


e@ Edit Utility 


This is a service routine called by the Monitor to process 
input messages, performing device-dependent transformations, 
and field validity checking, conversion and padding according 
to user-specified editing characteristics. 


e Qutput Utility 
This is a service routine executing as a subsystem to process 
output messages by performing device-dependent 
transformations, and then pass the messages to the Front End. 


For detailed documentation of these facilities, see Message 
Mapping Utilities and the Utilities Users Guide. 
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i Other service routines of the Intercomm system for processing 
requests associated with special subsystem design requirements are: 


e Store/Fetch 


This facility allows a subsystem to save and retrieve a 
temporary or permanent data string identified by a 
user-defined key. One or more subsystems can access each 


stored data string. (See Store/Fetch Facility. ) 


e Dynamic Data Queuin DD 


This facility allows a subsystem to save and retrieve a set 
of related data strings (a data queue) identified by a 
user-defined name. One or more subsystems can access each 
DDQ which may be transient or permanent. A DDQ may also be 
used for collecting messages destined for another subsystem, 


a printer, or even a batch program. (See Dynamic Data 
Queuing. ) 


r) CRT Page Facility 


This facility allows a subsystem to write a set of output 
messages to a CRT terminal-oriented Page Data Set. The first 
message of a set is also sent to the Front End 


automatically. The terminal operator may then enter commands 
processed by the Page subsystem to retrieve and browse 
% through the pages of a set of output messages. (See Page 


Facility.) 
e Data Base Management System Support (DBMS 


This facility consists of separate service routines for each 
supported DBMS (IDMS, System 2000, Model 204, ADABAS, TOTAL, 
DL/I, or a user DBMS), which allows access to the DBMS from 


Intercomn. (See the Data Base Management System Users 
Guide. ) 


e Dynamic File Allocation (DFA) 


This facility allows a subsystem to create (allocate) and/or 
access a sequential data set, or to access a VSAM data set, 
specifying its DSNAME as part of subsystem logic, rather than 
with execution JCL. (See Dynamic File Allocation. ) 


@ Signed-on Operator-Id Checking 


When executing under the security control of the Intercomm 
Extended Security System, a subsystem may call a service 
routine (SECUSER) to determine the user-ID of the operator at 
the terminal from which the transaction to be processed was 


entered. (See Extended Security System. ) 
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2.4 SUBSYSTEMS 


Intercomm-supplied subsystems are written in reentrant Assembler 
Language, and include the Output Utility, the Change/Display Utility, 
the Page Browsing Subsystem and many command processing subsystems. 


The Output Utility allows a programmer to specify predefined 
report and display formats so that simply constructed output messages 
. from a subsystem can be expanded, columnized, headed and subheaded, and 
displayed upon different types of devices without concern to the 
subsystem creating the message. Output Utility display formats can be 
changed without program modifications. 


The Change/Display Utility allows simple inquiry and file 
maintenance via predefined keyword input messages from terminals 
causing access to data files defined by tables. The Display Utility is 
used in conjunction with the Output Utility to produce varied report or 
display formats. 


The Page Facility processes commands from CRTI-type terminals to 
browse through a file of output display screens created by the PAGE 
system program. Subsystems make use of this feature by calling the 
page storage program during message processing. The terminal operator 
interacts with the Page Facility directly. 


Command processing subsystems process Intercomm standard messages 
to accomplish the start/stop of system functions, message switching 
between terminals, displaying and changing the status of system control 
parameters, display of statistics, etc. The commands and text syntax 


are described in System Control Commands. 


User-supplied subsystems accomplish application-dependent message 
processing. Each may call any Intercomm service routine or 
user-supplied subroutine, and may be written in COBOL, Assembler or 
PL/1. 


2.4.1 Reentrant vs Nonreentrant Subsystems 


In an interactive on-line environment, the probability is very 
high for more than one terminal operator to enter concurrent requests 
to be processed by the same _ subsystem. To accomplish the 
multithreading of concurrent requests, application subsystems should be 
coded as reentrant, that is, variable data is defined and processed in 
a dynamic working storage area obtained for the exclusive use of one 
processing thread. For Assembler Language subsystems, Intercomm 
provides entry and exit macros for obtaining and freeing the dynamic 
working storage area (save/work area), in addition to Intercomm 
equivalents of the IBM GETMAIN and FREEMAIN macros to obtain and free 
additional storage to hold messages, etc. to be passed to other 
programs. These macros are described in Chapter 3. 
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2.5 INTERCOMM TABLES 


Intercomm is a generalized on-line system monitor, requiring 
information about specific operating characteristics of a particular 


installation. This information is supplied in the form of tables 
generated with Intercomm macro instructions. Application programmers 
are usually not involved in defining the Intercomm tables, except for 
table specifications which pertain to their own applications. The 


basic tables controlling message processing are as follows: 
e Front End Verb Table (BIVRBTB 


A table listing all valid transaction identifiers (verbs), 
and relating them to the subsystem required for message 
processing. There is one entry per verb, defined via a 
BTVERB macro. 


e Front End Network Table 


Tables describing the terminal network (relating individual 
devices to five-character station identifications), device 
hardware and operating characteristics, and output message 
queuing specifications. 


e Back End Station Table (PMISTATB) and Device Table (PMIDEVTB 


Tables describing terminal identifications and 
device-dependent characteristics to the Message Mapping 
Utilities and/or the Edit and Output Utilities. 


e System Parameter List (SPA) 


A table describing system-wide operating characteristics, and 
consisting of two Csects: SPA and SPAEXT. The SPA Csect may 
be extended to include installation-defined table entries, 
accessible to all user subsystems and subroutines (see 
Chapter 8). This table is generated via the SPALIST macro. 


e Data Set Control Table (DSCT) 
A table generated by the File Handler describing on-line data 
sets. Information in this table is derived from JCL and file 
control (FAR) parameters at execution startup time. 


e Subsystem Control Table (SCT 


A table listing the program properties (reentrancy, language, 
entry point, etc.), message queue specifications (core and/or 


disk queues), and scheduling (resident or loadable, 
concurrent message processing limits, priority, etc.) for 
each subsystem. There is one entry per subsystem, defined 


via a SYCTTBL macro. 


The above listed tables are described in detail in the Operating 


Reference Manual. Additional tables describe detailed functions for 


the system programs, service routines and utilities. 
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2.6 INTERFACING WITH THE INTERCOMM MONITOR 


Each message processed by Intercomm consists of a 42-byte header 
prefix, plus application-oriented message text. The message header is 
prefixed to each input message by the Front End and is analyzed by the 
System Monitor for all message processing control. The particular 
fields of the header which control message routing are Receiving 
Subsystem Code (MSGHRSC) and Receiving Subsystem Code High-Order 
- (MSGHRSCH). This two-byte code is initialized by the teleprocessing 
interface when it constructs the header from the verb supplied at the 
beginning of the message text. The Front End Verb Table relates user 
verbs to their corresponding subsystem codes via coding of BTVERB 
macros (see Basic System Macros) in a user member USRBTVRB copied into 
the system BIVRBTB containing Intercomm system verbs. 


All subsystems are defined to Intercomm by an entry in the 
Subsystem Control Table (SCT). There is one entry for each subsystem 
which defines the program’s general characteristics, scheduling 
requirements and message queuing specifications. Each subsystem must 
be assigned a unique two-character subsystem code for message routing. 
Definition of Intercomm system subsystems for utility and command 
processing is provided in the released member INTSCT (formerly in 
PMISPA under Release 8). 


The Subsystem Control Table entry for each user subsystem is 
defined using the SYCTTBL macro which is coded in a user member USRSCTS 
copied into the system INTSCT at assembly time. A full description of 
the macro may be found in the Intercomm Basic System Macros manual. 


Many installations assign the responsibility of coding the 
Subsystem Control Table entries for individual user subsystems to the 
application programmer. At other installations, the Intercomm System 
Support Manager performs this task. In either case, the SYCTTBL macros 
must be coded with care, as there is one table controlling all user and 
system subsystems in operation when Intercomm is executing. 


The most significant SYCTTBL macro parameters for Assembler 
Language subsystems are: 


® LANG=RBAL 


For reentrant assembler language subsystems (LANG=NBAL if 
nonreentrant). 


@ SBS P=xxxxxxxx or LOADNAM=xxxxxxxx (for dynamic load) 


Label of entry point to which control is transferred when 
work is forwarded to subsystem (SBSP), or the load module 
name for dynamically loaded subsystems (LOADNAM). 
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TCTV=nnn 


Expected maximum processing time (in seconds) in a 
high-volume environment before the subsystem is assumed to be 
looping, or in an extended wait for file or data base access, 
and should be timed out. Considerations for this value 
depend on subsystem processing such as data base access, file 
updates, number and type of file accesses, exclusive control 
for file updates, number of output messages created, enqueue 
lock-out possibilities, etc. 


MNCL=nn 


Specifies the maximum number of concurrent threads that can 
be executed through this specific subsystem during a high 
activity period (when more than one operator enters 
transactions routed to this subsystem). 


RESOURC=name 


This parameter is used to control concurrent access to a 
resource (file, table, data base, etc.) across several 
subsystems in one Intercomm region. The name is also coded 
for the ID parameter of a RESOURCE macro (coded before all 
SYCTTBLs in the SCT) which identifies the shared resource and 
the maximum concurrent subsystem threads that may be 
activated for that resource. Note that the maximum share 
count coded on the RESOURCE macro overrides the combined MNCL 
value for all the subsystems "naming" that resource. An 
internal enqueue is issued (no time-out). While using this 
feature will affect response time during peak activity, it 
does not affect the TCTV for a subsystem, which goes into 
effect after shared control of the resource is granted. 


2.7 INTERCOMM MESSAGE HEADER 


The Intercomm message header is constructed by the Front End for 
each message when it arrives from a terminal. New messages created 
within the subsystem must be prefixed with the standard forty-two-byte 
header format, which is constructed by copying the input message header 
to an output message area and then altering appropriate fields. Figure 
7 lists the names and formats of all the fields in the message header, 
and describes their contents and changeability. 
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Alter 
Field Name Length Description Legend* 


MSGHLEN Length of message including 
header (binary number) 
MSGHQPR Teleprocessing segment I/0 code: 

02/F2=full message; 

00/FO=header segment; 

Ol/Fl=intermediate segment 

03/F3=final (trailer) segment 


MSGHRSCH High-order receiving subsystem code 


MSGHRSC Low-order receiving subsystem code 


MSGHSSC Low-order sending subsystem code 
MSGHMMN Monitor message number assigned by 
Message Collection (binary) 


MSGHDAT Julian date (YY.DDD)** 


MSGHTIM Time stamp (HHMMSSTH) 

MSGHTID Terminal identification (originating 
terminal on input messages, 
destination terminal on output) 
or Broadcast Group name 


MSGHCON Reserved area 


MSGHCON+1 Subsystem return code (for log code 
(MSGHRETN) X'FA’ entries only) 


MSGHFLGS Message indicator flags 


MSGHBMN Front End message number (binary) 


MSGHSSCH High-order sending subsystem code 


MSGHUSR Reserved*** 


ORG MSGHUSR Used for special processing 
MSGHADDR by the Front End (MSGHBMN-Rel. 8/9) 


MSGHLOG Log code (see Figure 11) 


MSGHBLEK Reserved area 


MSGHVMI | Verb or message identifier 
interpreted by receiving subsystem 


Figure 7. Intercomm Message Header Fields (Page 1 of 2) 
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Alter Legend: 


Y 


L 


Must be filled in for intersubsystem message switching and 
output messages passed to FESEND (MSGHVMI should be set to 
X'57' or X'6/7', as appropriate, for output messages passed 
directly to FESEND) 


Should be filled in for user's own information (required by 
Intercomm for message restart/file recovery and Log Analysis) 


Do Not Touch (must be copied from input to output message 
header area) 


May be modified for user codes based on subsystem logic 


** The period represents a one-byte message thread number (for resource 
management and/or message restart purposes). 


**XMSGHUSR is used by Intercomm modules as follows: 


l. 


If the BTVERB macro for the input verb has HPRTY=YES coded; 
contains a C’P' to request priority queuing for the 
subsystem. The user may move a C’P' to this field to request 
priority queuing for output messages to a terminal (via 
FESEND) or to another subsystem (via Message Collection). 


For messages to be processed by the Edit Utility, contains a 
C'F' to indicate that the input message was from a 3270 CRT 
and contains SBA sequences. 


For output messages to a switched async device (Teletype, 
Dataspeed 40, and 2740); a C'B’' requests disconnect after 
transmitting the output message. 


For output messages to a switched Teletype or Dataspeed 40 
device; a C’X’ requests using the alternate call-list for the 
next input message (as described in the BIAM Terminal Support 
Guide). 


For output messages discarded by the Front End, a C'F'’ 
indicates the message was flushed by command, a C’Z’ that it 
was discarded by the VTAM OTQUEUE user exit (Release 10 
only). 


If none of the above considerations are applicable, the subsystem 
may use this field for messages queued to other user subsystems, 
or for special logging information. The LOGPRINT utility always 
prints the value coded in this field (in hexadecimal). 


Figure 7. Intercomm Message Header Fields (Page 2 of 2) 
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249 51 MSGHOPR and MSGHVMI Fields 


In general, an Assembler Language application subsystem does not 
need to be concerned with the MSGHQPR field, unless processing long 
input from a Teletype or similar device where message input may be 
segmented. In this case, the DDQ Facility must be used to store and 
forward the input message segments. Otherwise, input messages from the 
Front End always contain a QPR of C'2'. Both MMU and the Output 
-Utility set the QPR to X’02' for output messages unless the Output 
Utility finds it necessary to segment an output message, in which case 
a segment code is used. The various uses of the MSGHVMI field for 
input and output message processing may be determined from the index 
references to this field at the end of this manual. 


2.8 INTERCOMM MESSAGE FLOW USING MESSAGE MAPPING 


The interaction of Intercomm system components, tables and 
subsystems with the Message Mapping Utilities (MMU) is summarized in 
Figure 8; the path of one input message and its corresponding output 
message is traced, and the numbered arrows in the diagram correspond to 
the numbered paragraphs below. 


1 The Front End reads an input message and prefixes a 42-byte 
control header containing routing information, time, date, 
originating terminal and message length. The message is then 
queued for subsystem processing by Message Collection. 


2 The System Monitor schedules the subsystem and retrieves the 
message based upon the Subsystem Control Table (SCT) 
scheduling criteria. 


3 The message is passed to the subsystem. 


4 Input in terminal-dependent format is transformed to a 
terminal independent form by a call to a Message Mapping 
Utility (MMU). 


5 The subsystem performs message processing logic, requesting 
I/O service functions from the File Handler or Data Base 
Manager interface. 


6 The subsystem creates one or more terminal-dependent output 
messages by calling MMU. 


7 The subsystem passes the message formatted by MMU to the 
Front End by a call to FESEND (unless MMU is asked to perform 
this function). 


8 The subsystem returns control to the System Monitor, passing 


a return code indicating normal completion or an error 
condition. 
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In the Intercomm multithread environment, this same sequence of 
events is carried out concurrently for many messages. 


VERB 
TABLE SUB- 


& MESSAGE SYSTEM 
FRONT END COLLECTION QUEUES 


MESSAGE 
MAPPING 
UTILITIES 


SYSTEM APPLICATION 
MONITOR SUBSYSTEM 


FESEND 


ACCESS FILE HANDLER 
METHOD OR OR DATA BASE 
DATA BASE MANAGER 

MANAGER INTERFACE 


Figure 8. Intercomm Message Flow Using Message Mapping 
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229 INTERCOMM MESSAGE FLOW USING EDIT AND OUTPUT 


The path of one input message and its corresponding output 
message is traced in Figure 9; the numbered arrows in the diagram 
correspond to the numbered paragraphs below. 


1 The Front End reads an input message and prefixes a 42-byte 
control header containing routing information, time, date, 
originating terminal, and message length. The message is 
then queued for subsystem processing by Message Collection. 


2 The System Monitor schedules the subsystem and retrieves the 
message based upon the Subsystem Control Table (SCT) 
scheduling criteria. 


3 The unedited message is passed to the subsystem. 


4 The subsystem calls the Edit Utility (if required) and the 
input message is edited according to the Edit Control Table 
(ECT). 


5 If editing is not successful due to invalid input data, the 
Edit Utility optionally creates an error message for the 
originating terminal and queues it for the Output Utility by 
calling Message Collection, before returning an error code to 
the subsystem. If editing is successful, the edited message 
is passed back to the subsystem. 


6 The subsystem performs message processing logic, requesting 
I/O service functions from the File Handler or Data Base 
Manager interface. 


/ The subsystem creates one or more output messages and queues 
them for the Output Utility by calling Message Collection. 


8 The subsystem returns control to the System Monitor, passing 
a return code indicating normal completion or an error 
condition. 


9 The System Monitor schedules the Output Utility and passes 
the output message(s) to it for processing. 


10 The Output Utility performs formatting, if specified in the 
header, according to entries in the Output Format Table 
(OFT), finally passing the message to the Front End via a 
call to FESEND. 


ll The Output Utility returns to the System Monitor. 
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Figure 9. Intercomm Message Flow Using Edit and Output 


25 


Chapter 2 Message Processing and 
Control Under Intercomm 


2.10 THE INTERCOMM SYSTEM LOG 


The Intercomm system log (INTERLOG) provides system journaling 
and maintains a historical record of all traffic within the system. 
Complete documentation of performance during on-line processing is 
thus provided, along with system control for restart/recovery. 


Message traffic is recorded at the time of entry on a subsystem 
queue, and at the time message processing begins and ends within each 
subsystem. Subsystems may make user entries on the system log by 
calling an Intercomm system program (LOGPUT). 


An installation may suppress some or all log entries, depending 


on its own requirements. The system log is optionally used at 
Intercomm system restart time to restore message traffic within the 
system at the time of failure. The logging entries are blocked and 


written to a variable-length sequential data set which may reside on 
disk or tape. 


Log entries are in one of two formats: HT--42-byte message 
header and full text, as the message arrives from a terminal and is 
queued for a subsystem, or queued for a terminal; or HO--header-only 
entries, to mark progress through the system or error conditions. 


Log entries are identified by a code in the MSGHLOG field of the 
message header. The time and date stamps (MSGHTIM and MSGHDAT) in the 
message header are updated for each log entry. 


Progress of a message through a specific subsystem, or through 
the Front End, is indicated by the same Monitor Message Number 
(MSGHMMN) in each log record (01-30-FA or F2-F3). Complete progress 
of a message, from the first processing subsystem to final 
transmission, is indicated by the same Front End Message Number 
(MSGHBMN). The log may be printed completely or selectively via the 
Intercomm off-line utility LOGPRINT, described in the Operating 
Reference Manual. 


A timing analysis utility (Log Analysis), which is supplied with 
Intercomm, may be used off-line to produce a report of message queuing 


and processing time. Statistics for messages by terminal, verb, 
subsystem, and/or system totals are provided. See the Operating 


Reference Manual. 


The logging entries may be input to user-written batch programs 
to provide performance analysis in detail, such as traffic vs. network 
configurations, accounting routines, etc. 


Figure 10 illustrates the log entries for one input message and a 


corresponding output message generated via the Output Utility. Number 
6 appears only if executing in Test mode, since there is no Front End. 
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For live or simulated mode Intercomm, two additional entries are an F2 
log code (HT) when the message is queued for the Front End via FESEND 
(appears in place of the 40 log entry between the 30 and FA entries), 
and an F3 log code (HO) when the message was transmitted by the Front 
End. Logging of the message to be transmitted (log code F2) occurs 
before final Front End processing (idles insertion, New Line to SBA 
sequence conversion, etc.). 


If Message Mapping is used and the message is passed to the Front 
End via FESEND (Figure 8), only the log entries numbered 1, 2, and 7 
appear for each message processing thread. Log codes 3, 4, and 5 
represent the additional processing for a message passed to the Output 
Utility (receiving code U). 


© 
So 


OPTIONAL 


3S 


MSGCOL 
log code O1 
HT 


MONITOR 
log code 30 
HO 


APPLICATION 
log code 
41-6F 
HT 


MSGCOL 
log code 01 
HT 


HT = Intercomm message header and message data 
HO = Intercomm message header only 


Figure 11 describes all the Intercomm log codes. 
log entries may only use the codes in the range X’41' to 


Figure 10. 


Sequence of Log Entries 
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Internal |External Restart 
Code Format | Description Use 
X‘'00' Checkpoint Record Checkpoint | Yes 
C'2' Message queued for subsystem Message 
by Front End or a subsystem Collection | User 

C’R’ Message restarted through LOGPROC User 
the system 

Cre Message restarted--related LOGPROG User 
to Data Base Recovery 

C'T’ Message passed to subsystem Subsystem | User 
for processing Controller 

C’Z' Message passed to Front End FESEND No 
(test mode only) 

X'41'- User called LOGPUT Any No 

X'6F’ Subsystem 

X' 80! - File Recovery before-images IXFLOG User 

X' 8E’ 

X' 8F Checkpoint Records indicator IXFCHKPT Yes 

X' 90! - File Recovery after-images IXFLOG User 

X'9E’ 

X'9F’ Intercomm Startup LOGPUT Yes 

X' AO’ Message restart begun LOGPROG Yes 
X'Al’ | | Message restart finished: LOGPROC Yes 

all subsequent log entries 
produced by live Intercomm 

X' AA’ Intercomm Closedown LOGPUT No 
X' CO! Region started (Multiregion MRINTER No 

only) (Text=Region-id(s) ) 
C'A’ Message successfully queued MRQMNGR User 


for Satellite Region CR onl 
Internal Code: 
External Code: 
Format: 
Restart Use: 


Log code in core during processing (snaps and dumps) 
Log code after translation by LOGPUT (INTERLOG printout) 
HT for header and text, HO for header only 

Yes, No, User (specified via user-coded system macros) 


Figure 11. INTERLOG Entries (Page 1 of 2) 
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Restart 
Format | Description igi Use 
Message successfully passed User 
to Satellite Region 
c'C’ Message lost (Region/Hold Q User 
full) or flushed (SR/SS down) 
c't' Sign on/off processing, No 
security violation messages 
c'3' Normal message complete User 
c’5!' Unprocessed message--invalid User 
subsystem/QPR code 
c’6' Unprocessed message--core and User 
disk queue full 
c’8' Message cancelled--program User 
error or time-out, I/O error, 
or flushed by command (Rel 10) 
Cro. Message flushed by Retriever, Retriever No 
used when application program 
does not obtain (via GETSEG) 
all parts of a segmented 
message; or message failed 
security check SYCT400 
c'l' Message after verb USRBTLOG No 
verification (optional) 
C'2' Message queued for User 
transmission 
c'3' Message transmitted, User 
discarded (MSGHUSR=Z), (Rel 10) 
or flushed (MSGHUSR=F) (Rel 10) 
c'4' 3270 output message content No 
invalid--message dropped. 
c'5'- Transmitted DDQ msg status: No 
c’8' see SNA Term. Support Gd. 
K' FF’ Intercomm Restart Accounting Yes 


Figure 11. INTERLOG Entries (Page 2 of 2) 
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2.11 ADDITIONAL APPLICATION PROCESSING FACILITIES 


In addition to the application programming facilities described 
in this and related manuals, the application designer should be aware 
of the following processing options available under Intercomm: 


e Off-line batch region execution: the Intercomm File Handler, 
DFA, DDQ, Store/Fetch and MMU may be executed by an off-line 
program (coded as non-reentrant) to prepare a file, data 
strings, or messages for on-line access. See the associated 
manuals for linkedit considerations. 


e Multiregion Facility batch region interface: when executing 
an on-line Multiregion system, any batch application region 
may pass a message or a FECMDDQ (see also Chapter 9) to an 
on-line subsystem or to the Front End via the Output Utility 


subsystem. See Multiregion Support Facility. 


e Time controlled processing: instead of being triggered by an 
input terminal message, an application may be designed to 


execute at a particular time of day. See the Operating 
Reference Manual. 


6 Segmented input message processing via DDQ: segmented input 


messages, whether gathered by Intercomm from a remote device 
(CPU, etc.) or generated by an application program, are 
placed on a DDQ and may be serially passed to an application 
subsystem via a DDQ Facility interface. See Dynamic Data 
Queuing. 


e Dynamic linkedit feature: dynamically loaded user subsystems 
and subroutines are linkedited to called Intercomm resident 
routines at startup, thus reducing the size of the load 
modules. The LOAD system control command is used to force a 
relinkedit of a new version of a dynamically loaded program 
placed on the load library while Intercomm is executing. See 


the Operating Reference Manual. 


e User exits: various user exits for installation dependent 
processing are listed in the Qperating Reference Manual. 
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CODING AN INTERCOMM SUBSYSTEM IN ASSEMBLER LANGUAGE 


a PROGRAM STRUCTURE 


An application subsystem executing under Intercomm control is 
activated to process one message. The following examples typify the 
concerns of message processing logic: 


l. Interpretation of message text to reroute administrative data 
to another terminal. 


2. Editing of message text, creation of a record on a sequential 
data set for later off-line processing and preparation of an 
acknowledgement message to the originating terminal. 


3. Editing and analysis of message text to determine file 
retrieval and/or update criteria, data file access, 
preparation of a response message for the operator at the 
originating terminal. 


4. Analysis of an application-oriented control message and 
appropriate action, such as checking batch totals from 
example 2, above, or acting on a special request to close a 
file or perform some other control function. 


This chapter presents techniques for coding a BAL application 
subsystem to execute in the Intercomm region, and to use Intercomm 
message processing facilities. While some facilities are referenced 
here, they are fully described in another chapter: check the index for 
specific routines. To bring all the coding requirements into proper 
perspective, this chapter includes a sample Intercomm application 
subsystem. Its objective is to "echo" the text of an incoming message 
back to the originating terminal. 


A BAL application subsystem is coded as a reentrant subroutine, 


as illustrated in Figure 12. A subsystem’s logic is designed to 
analyze and process one input message, it does not contain logic for 
terminal I/O operations. Figure 13 depicts the components of a BAL 


application program environment. 


Subsystem Controller activation of the application subsystem is 
achieved via the equivalent of a CALL macro instruction. On entry to 
the subsystem, the address of a three-word parameter list, as listed 
below, is passed via register 1: 


e Address (fullword-aligned) of message to be processed, 
consisting of a 42-byte header and text (edited or unedited) 


® Address of the System Parameter Area (SPA), for accessing 
addresses of Intercomm service routines and user data that 
may be used for processing the message (see Appendix D) 


e Address of the program's Subsystem Control Table (SCT) entry, 
which allows the subsystem to reference such information as 
its subsystem code, execution priority, etc. 
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2 


Reference 
SUBSYSXX CSECT description 
REGS in text 


*SUBSYSTEM ENTRY 
LINKAGE 


*MESSAGE PROCESSING LOGIC 


*GET CORE FOR OUTPUT MESSAGE 
STORAGE 


Build Output Message 


*PASS THE MESSAGE TO THE FRONT END VIA FESEND, OR 
*QUEUE THE OUTPUT MSG VIA MSGCOL 
CALL 


*FREE THE INPUT MESSAGE 
STORFREE 


*SUBSYSTEM EXIT 


oo i i oF ee So 


RTNLINK 
* 
INMSG was?” 
INHDR CL42 
INTEXT 

é define input text format 
INLEN *-INHDR 
* 
OUTHDR OCL42 
MSGHDRC 
OUTTEXT 
define output text format 
OUTLEN * -QUTHDR 
* 
WORKAREA DSECT (*) 
REGSAVE DS 18F 
COREADDR DS F 
PARMSAVE DS SF 
SUBSYSWK DS 
: define subsystem dynamic work area 

WORKLEN EQU *-REGSAVE 

END 

Figure 12. Reentrant Assembler Subsystem Structure | 
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SYSTEM 


INTERCOMM PARAMETER 


SYSTEM 
\ 3B / SUBSYSTEM 
REENTSBS CONTROL 
LANGUAGE TABLE 
INTERFACES AA XX YY 
SUBSYSTEMS 
SUBSYSTEM AA 


REENTRANT 
BAL SUBSYSTEM BB 


MVS 
INTERCOMM DYNAMIC POOL STORAGE SUBPOOLS 
(1a) BB INPUT (18) BB INPUT 
MESSAGE A MESSAGE B FILE 
AREAS 
Dynamic Work Dynamic Work 
Space For Space For 
SUBSYSTEM BB SUBSYSTEM BB 
Thread A: Thread B: 


SAVE AREA | 
INDEP ITEMS 
RECORD AREAS 
OUTPUT MSG 


SAVE AREA _ MVS ACCESS 
INDEP ITEMS METHODS 
RECORD AREAS 

OUTPUT MSG 


Figure 13. Reentrant Application Program Environment 
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After a subsystem completes processing and returns control to the 
Subsystem Controller (see Chapter 2), the Intercomm return code (in 
Register 15) is checked to determine whether the message should be 
cancelled due to an error. Then the return code is placed in the 
externally saved input message header in MSGHRETN (MSGHCON+1), and the 
header is logged with an appropriate log code (see Chapter 2). Figure 
14 describes Intercomm return codes. If the subsystem (or a called 
subroutine) program checks, or the return code is 8 or 12, USRCANC 
returns an appropriate error message to the terminal operator. USRCANC 
is a user exit provided by Intercomm under the name PMICANC, and is 


described in the Operating Reference Manual. 


Subsystem Controller 
Error Action 


Meaning 


Successful completion 


Unrecoverable error 
condition (no core, 
MAPEND error, etc.) 


User codes to identify 
unusual condition 
File or DBMS Update 
Subsystem, no message 
restart required* 
File or DBMS Inquiry 
Subsystem, message 

restart required* 


912 Force Backout-on-the-Fly* File updates or additions backed out 


*See File Recovery Users Guide or Data Base Management System 
Users Guide 


Figure 14. Intercomm System Return Codes 
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Sue MESSAGE PROCESSING CONCEPTS 


The application program receiving the message may analyze the 
Verb Message Identifier (MSGHVMI) in the header and/or message text 
fields to further control message processing logic. The meaning of 
different VMI values is dependent on the design requirements of the 
program receiving the message. For example, the Front End sets the VMI 
to X‘'00' to indicate to the Assembler subsystem that editing by the 
Edit Utility is required, based on the specification in the Front End 
Verb Table for a given verb (BIVERB macro, EDIT parameter). The 
Assembler subsystem then analyzes the VMI to determine if the Edit 
Utility should be called. A VMI value of X'FF' (high-values) indicates 
that no processing is required by, or was performed by, the Edit 
Utility. Any other value in the VMI indicates that the Edit Utility 
has already processed the message or that a user subsystem has placed a 
code in the field before switching (queuing) the message to the 
currently processing subsystem. 


An application subsystem creates an output message by building a 
42-byte header and appropriate message text. This new message is 
either passed to the Front End via FESEND for transmission to the 
terminal, or is queued for later processing by the Output Utility or 
some other subsystem by calling the Intercomm system program MSGCOL. 
The subsystem destined to receive this new message is determined by the 
receiving subsystem code fields (MSGHRSC, MSGHRSCH) in the message 
header. The receiving subsystem may then analyze the VMI, as 
appropriate. The Output Utility, for example, analyzes the VMI to 
determine whether or not prespecified output message formatting is to 
be performed. If the output message is passed directly to FESEND, 
MSGHRSCH and MSGHRSC should be set to binary zeros. 


Subsystem logic for input message text analysis and output 
message text creation varies, depending whether Message Mapping or the 
Edit and Output Utilities are used. Figures 15 and 16 illustrate 
subsystem processing logic for these two cases. 


It is very important to note that the input message area 
(Intercomm header and message text) may only be examined (treated as a 
read-only area) by the application program. It may also be copied to 
an output message area (header only, or header and text) where it may 
be added to or changed, depending on program logic. Never add to, or 
change, the input message text area. 
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Subsystem Logic 
ENTRY 


Initial- 
ization 
Logic 


MAPIN 
according to 
user specifi- 
cations 


Processing 
Logic 


Prepare 
Output 
Data 


MAPOUT 


according to 
user speci- 
fications 


MAPEND 


place message 
header and 
text_in DWS 


FESEND 
place message 
in terminal 
queue for 
transmission 


Figure 15. 


Coding an Intercomm Subsystem 
in Assembler Language 


Comments 


LIE aT SEM ee SRE Sa ne ate ae oe See ee es SE TE Er ee ae ens 


The subsystem determines (perhaps based 
on the particular verb entered) if the 
input message requires mapping. 


MAPIN is called to convert the input 
message to text consisting of fixed 
length fields with a three-byte prefix of 
length (two bytes) and flag (one byte), 
indicating the result of field conversion. 
All terminal-dependent characters are 
removed. 


Processing logic is application-dependent. 


Output text data has a format similar to 
mapped input text: fixed length data 
fields with a three-byte prefix of length 
(two bytes) and attribute (one byte), 
indicating terminal-dependent field 
characteristics, if applicable. 


MAPOUT is called to build an output 
message text stream, padding, justifying 
and/or converting data fields from 
computational form, as necessary, and 
adding constant heading information as 
required. 


MAPEND is called to return the output 
message (header and text) in terminal- 
dependent format ready for transmission, 
or to dispose of the output message. 


FESEND is called to pass the output 
message to the Front End (if MAPEND has 
not disposed of the output message). 


Subsystem completes its processing and 
returns to Intercomm. 


Subsystem Logic Using Message Mapping Utilities 
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Comments 


Sheen a er A Ta neo a ae ee eat te a 


The subsystem determines whether or not the input 
Initial- message requires Edit (VMI=X’00’ if yes) and CALLs 
ization the Edit Utility, EDITCTRL, to accomplish field 
Logic conversion. After Editing, the message text 
consists of fixed length data fields, or variable 
length data fields prefixed with a l-byte ident- 
ification and a l-byte length code (binary 
values). Return codes indicate error conditions. 


Processing Processing logic is application-dependent. 
Logic 


The subsystem prepares an output message by 
creating a message header and the appropriate 
Prepare text. Output message text fields are either 


Output fixed length data fields or variable length 

Message fields with a prefix as described for Edit, above. 
Message header fields RSCH, RSC, and VMI identify 
the specific message text format. 


MSGCOL 


queue the MSGCOL is called to queue the output message for 


message for processing by the Output Utility subsystem. 
Output 


Final Subsystem completes its processing and returns to 
Processing Intercomm. 


Figure 16. Subsystem Logic Using Edit and Output Utilities 
(Page 1 of 2) 
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Subsystem Logic Comments 
ENTRY 


Output Utility The Output Utility performs message formatting 
message for- according to user specifications, adding constant 
matting logic heading information as required. 


|___FESEND _it 
put message FESEND is called to pass the output message to the 
in terminal Front End. Output completes its processing and 
queue returns to Intercomn., 


Figure 16. Subsystem Logic Using Edit and Output Utilities 
(Page 2 of 2) 
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When a message is received in the Intercomm region, it undergoes 
various preprocessing functions by the system. The Front End prefixes 
the message with a 42-byte header and the message is queued for 
processing. The Subsystem Controller, a component of the Intercomm 
Monitor, will schedule, load (if necessary), and activate the 
application subsystem for the message. If the subsystem is loaded 
above the l6émeg line under XA, it will receive control in 31 Amode. 


At this point, message processing logic begins. At least eight 
major functions will be included in the subsystem’s structure to 
process a message. These are paired as follows: 


@ Entry and Exit from the Subsystem 


The subsystem must provide necessary logic to link with 
Intercomm (that is, initialize registers, acquire and chain a 
save area, etc.), and to return to the monitor (restore 
registers, free the save area). The LINKAGE and RTNLINK 
macros are provided for subsystem linkage processing. 
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e Edit and Process Message 


The incoming message is often unedited. The subsystem is 
responsible for all conversion or editing. Message Mapping 
Utilities or the Edit Utility may be used for this purpose. 
The message is then analyzed and processed by subsystem 
logic, using Assembler Language instructions, Intercomm or 
operating system supplied macros, and/or Intercomm service 
routines. 


e Obtain and Free Core 


The Assembler Language application subsystem is responsible 
for obtaining storage as needed from the Intercomm dynamic 
pool area, and then freeing the storage when processing is 
completed (if necessary). The Intercomm STORAGE and STORFREE 
macros are provided to obtain and free core. 


e Build and Queue the Output Message 


As part of the message processing logic, a subsystem may 
create one or more messages to transmit to a terminal. 
Message Mapping Utilities may be used in conjunction with the 
FESEND routine, or the Page or Dynamic Data Queuing 
Facilities, to create and queue the output message(s) for 


transmission. Or, the output message(s) may be created and 
queued for processing by the Output Utility via a call to 
MSGCOL. The Output Utility may be used to format the 


message(s), and subsequently pass the message(s) to FESEND 
for transmission. 


The subsystem consists of two areas: the actual message 
processing logic; and the definition of areas of core in the Intercomm 
dynamic pool storage area. Figure 12 illustrates the structural flow 
of an application subsystem. The circled numbers are included to 
facilitate reference in the following text discussion. 


3.3.1 Subsystem Entry 


Entry into the subsystem is identified by the CSECT name or an 


ENTRY name. The address of the three-word parameter list passed on 
entry by the Subsystem Controller is in register 1. The input message 
resides in the dynamic pool area. The message format must be defined 
within the application program by a DSECT (see in Figure 12). 


Parameters 2 (SPA) and 3 (SCT-entry) addresses are resident areas in 
the Intercomm load module, but a DSECT must be generated if these areas 
are to be referenced. The LINKAGE macro (see in Figure 12) will 
provide these Dsects (as described in the next section), or the 
programmer may generate the Dsects as part of the subsystem structure. 
Intercomm Dsects for use by Assembler Language application programs, 
and methods for generating them (macro or COPY statement) are described 
in Appendix B. 
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3.3.2 Linkage 


To allow concurrent processing of messages within a _ subsysten, 
the subsystem must be coded in a reentrant form. The LINKAGE and 
RINLINK macros generate much of the code necessary to make an Assembler 
Language subsystem reentrant. The LINKAGE macro generates all of the 
instructions necessary to establish standard reenterable linkage from 
the Subsystem Controller into the application subsysten. LINKAGE 
provides addressability, and can also perform a number of other service 
functions for the application subsystem: 


@ Provide a set of register equates 
e Issue various USING statements 
@ Set up one or two base registers 


® Set up specified registers with addresses passed in the 
parameter list 


e@ Obtain a dynamic save/work area from the dynamic pool area 
and zero the core obtained 


e Provide the PARMLIST, SPALIST, SCTLIST, MSGHDR, R13 DSECTs, 
as desired. (See also (8) and in Figure 12.) 


The LINKAGE macro must be the first executable instruction in the 
application subsystem structure. The coding requirements to ensure 
reentrancy are: 
1) Code the LINKAGE macro at the main entry point of the sub- 
system (see in Figure 12). 


2) Code the RTNLINK macro (see ©) in Figure 12) to return 
control to the calling program (Subsystem Controller). 


3) Do not modify any area within the program. Only modify 
dynamic storgge obtained by using the LINKAGE and STORAGE 
macros (see G) in Figure 12). 


4) Use the list and execute forms of any IBM operating system 
macros and Intercomm macros (when applicable). Intercomm 
processing macros are listed in Chapter 10. 


3.3.3 Message Processing 


The next section of the subsystem structure contains the message 
processing logic as indicated by (2) in Figure 12. Further 
considerations for message editing and text formats are described in 
Chapter 2. If a file is to be accessed as part of the processing of 
the message, a File Handler service routine must be called to read from 
or write to a file (described in detail in Chapter 6). See other 
chapters in this manual for detailed descriptions of service routine 
calls for other processing facilities, and Chapter 10 for a list of 
available macros. 
40 
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Once the processing has been performed, an area of dynamic core 
may be needed to construct the output message. _The Intercomm STORAGE 
macro must be used to obtain dynamic core (see in Figure 12). The 
STORAGE macro instruction issues a request for ownership of a portion 
of core. If the request is satisfied, register 15 will contain a 
return code of O and the core allocated will commence on a double word 
boundary. If the request for dynamic core is not satisfied, register 
15 will contain a return code of 8. Core obtained via the STORAGE 
macro must be released through the use of the STORFREE macro 
instruction, unless that core is utilized for a message queued for 
another subsystem, or the Front End. 


Once dynamic core has been obtained, the subsystem can construct 
the message for output, consisting of a 42-byte header prefix, plus 
application-oriented message text. This new message is passed directly 
to the Front End by calling the system program FESEND, or is queued for 
later processing by the Output Utility or some other subsystem by 
calling the Intercomm system program MSGCOL, indicated by in Figure 
12. The subsystem destined to receive this new message is determined 
by the receiving subsystem code fields (RSC, RSCH) in the message 
header. The Receiving Subsystem may then analyze the Verb/Message 
Identifier (VMI), as appropriate. The Output Utility, for example, 
analyzes the VMI to determine whether or not prespecified formatting is 
to be performed. 


If the output message text is shorter than the actual area 
obtained, the STORFREE macro is used to free the extra area. This is 
accomplished by calculating the difference between the length of the 
area obtained and the length (contained in the message header) of the 
actual output message, as illustrated below: 


hdr text u 


nused 
WIT ILL ALLL LALLA LLL 


obtained with STORAGE 


free with STORFREE 


LA R14, OUTLEN Total LEN acquired less 
SH R14 ,MSGHLEN actual LEN used=unused LEN 
SRL R14,3 Drop down to nearest 
SLL R14,3 multiple of 8 
LTR RO,R14 RO=unused length 
BZ NOFREE If less than 8, nothing to free 
LR R1,R7 Pick up addr of unused core by 
AH R1 ,MSGHLEN bumping to end of used portion 
ROUND Rl Up to next multiple of 8 
STORFREE ADDR=(1) , LEN=(0) Free unused core 

NOFREE DS OH 
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As indicated by @ in Figure 12, the subsystem must use the 
STORFREE macro to free e input message area, unless that area has 
been freed by a call to MAPIN, or has been referenced in a call to 
Message Collection (see "Additional Coding Techniques" below). The 
system routines MSGCOL and FESEND take over "ownership" of the passed 
message area. 


The RINLINK macro instruction is coded in coordination with the 
LINKAGE macro instruction. It restores the registers saved at LINKAGE 
time and optionally frees storage acquired by LINKAGE. In addition, it 
effects the return to the Subsystem Controller and passes a return code 
(see Figure 14) in register 15. See on Figure 12. 


Note that the SPA parameter of the RINLINK macro must be coded if 
the register containing the address of the SPA differs at the time of 
RINLINK from the register used at the time the LINKAGE macro is issued 
or if the subsystem is dynamically loaded. 


3.3.4 Additional Coding Techniques 


To minimize the amount of dynamic subpool space utilized by an 
application subsystem, the programmer may optionally use the input 
message area as the output message area as text processing logic 


allows. However, if using this method, the output message must never 
be greater in length than the input message. This approach is well 
suited (although not limited) to fixed-length message text. If the 


output message is shorter than the input message, additional program 
logic is required to free the remaining area of the input message not 
utilized as output message text. Remember that STORFREE operates on 
doubleword boundary alignment. Also, the new shorter message length 
must be stored in the message header before calling MSGCOL or FESEND. 


A second technique for obtaining core for an output message which 
minimizes dynamic pool area fragmentation (but adds internal processing 
overhead) is to allow the LINKAGE macro to obtain space for an output 
message as well as other work areas. In this instance, the output 
message area must appear at the "trailing end" of the obtained area. 
RINLINK must be coded to free up all of the save/work area except the 
output message area, which is controlled by Message Collection (or 
FESEND). However, the subsystem must use STORFREE for any trailing 
area of core not occupied by the output message. 


The following illustrates the areas of dynamic core operated upon 


by two different subsystems and the associated responsibilities for 
obtaining and freeing core. 
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INTERCOMM 


Application Application 
Subsystem PROGRAMS Subsystem 


A B 


DYNAMIC POOL AREA 


Application A 
register save 


(4) input message area B 


Application B 
register save area 
Application B 
work area 


Application A 
work area 


fr 
) 
> 
a 
0) 
fo 
> 


utput mess 


area obtained by Monitor, freed by subsystem A 
area obtained by LINKAGE, freed by RINLINK 


area obtained by STORAGE, passed to MSGCOL or FESEND, — 
area not used for message freed by STORFREE (shaded area) 


area obtained by Monitor, freed by subsystem B 
area obtained by LINKAGE 


area freed by RTNLINK 


OOOO OOO 


passed to MSGCOL, area not used freed by STORFREE (shaded area) 
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3.3.5 Subsystem Illustration 


Figure 17 illustrates the basic coding required to implement an 
Intercomm subsystem and the definition of an input message and 
creation of an output message via an application to "echo" the text of 
an incoming message back to the originating terminal. The Message 
Mapping Utilities, or the Edit Utility and the formatting capabilities 
of the Output Utility, are not used. 


1. The message header is created by copying the input message 
header to the output message header area and adjusting the 
following fields: 


e MSGHSSCH, MSGHSSC--Sending Subsystem Code 


Move the original receiving subsystem code values, 
MSGHRSCH (to MSGHSSCH) and MSGHRSC (to MSGHSSC), to 
identify the current subsystem as the sending subsystem. 


e MSGHRSCH, MSGHRSC--Receiving Subsystem Code 


Move in a predefined code to indicate further processing 
(the next subsystem) for this message (for FESEND, use 
binary zeros). 


e MSGHVMI--Verb/Message Identifier 


Move in a predefined code to indicate the output message 
is not fully formatted: X’57’. If an output message is 
formatted by MMU, do not touch this field. 


e MSGHLEN--Message Length 


Modify to total header and text length of output message 
(if different from length of input message). 


e MSGHTID--Receiving Terminal Name 


If the originating terminal is to receive the response 
message, do not change. Otherwise, specify the receiving 
terminal name for the output message. 


To assist the programmer in defining the message header, 
there is a source library member, MSGHDRC, that may be copied 
into the appropriate DSECT area in the source code. See 
Chapter 2 for a description of individual fields in the 
message header. 


2. The new message text is created by copying the input message 
text to the output text area. 


3. Queuing of the output message for the terminal is 
accomplished via the service routine FESEND. 
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4, The return code from the queuing routine must be analyzed to 
assure that the new message was actually queued, and recovery 
action taken if not. 


5. The last logical activity in the subsystem is to STORFREE the 
input message and then issue the RINLINK macro, returning 
control to the Subsystem Controller and passing back an 
appropriate return code. 


The program Csect or Entry Point name must correspond to the 
subsystem entry point described in the Subsystem Control Table. If 
dynamically loadable, the load module name should be the same as the 
Csect name. The entry parameters for the System Parameter Area (SPA) 
and Subsystem Control Table (SCT) entry for the subsystem are not 
detailed as there is no need to reference any of their individual 
fields. 


The input and output message formats are described via Dsects, 
with the message header detailed for the output message area. 
Constants and an LTORG statement are usually defined between the last 
code instructions and the Dsects area. Areas of storage modified 
during program execution must be defined within the dynamic save/work 
area Dsect. Such items also include storage areas required for 
Intercomm service routines and passed to those routines as parameters, 
whether or not the subsystem references or modifies those areas. For 
programs eligible for loading above the 1l6meg line under MVS/XA or ESA, 
unmodified constant values (map names, file ddnames, etc.) must be 
copied to the save/work area for passing as parameter values to called 
Intercomm routines. Additionally, areas passed as parameters to user 
subroutines must also be defined in the save/work area. 
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* REENTRANT BAL SUBSYSTEM TO ‘ECHO’ A MESSAGE, 


% % % 


USING INMSG,R5 
USING OUTMSG,R6 
USING WORKAREA ,R13 
REGS 

* SUBSYSTEM ENTRY 


ILLUSTRATING BAL SUBSYSTEM STRUCTURE. 
MESSAGE PROCESSING LOGIC CONSISTS ONLY OF CREATING AND QUEUING 
AN OUTPUT MESSAGE TO RETURN TO THE ORIGINATING TERMINAL 


GENERATE REGISTER EQUATES 


LINKAGE BASE=(R12) , LEN=WORKLEN , PARM=(R2) ,SPA=(R3) ,MSG=(R5) 


* GET CORE FOR THE OUTPUT MESSAGE AREA 


LH R8 , INMSG 


INPUT MESSAGE LENGTH 


STORAGE ADDR=COREADDR , LEN=(R8) , LIST=PARMSAVE 


LTR R15,R15 
BZ GOTCORE 


LA R10,8 
B FREEIN 
GOTCORE L R6 , COREADDR 


* BUILD OUTPUT MESSAGE 
MVC OUTHDR , INHDR 
MVC $MSHGSSCH,MSGHRSCH 
MVC MSGHSSC , MSGHRSC 
MVI MSGHRSCH ,X’00’ 
MVI MSGHRSC ,X’00’ 
MVI MSGHVMI ,X'57' 


LA RY , 42 
SR R8 ,R9 
EXMVE OUTTEXT, INTEXT,R,R8 
AR R8 ,R9 


TEST RETURN CODE 
RETURN CODE 8 IF NO CORE 
ESTABLISH ADDRESSABILITY 


INPUT HEADER TO OUTPUT HEADER 
THIS SUBSYSTEM BECOMES THE 
SENDING SUBSYSTEM 
THERE IS NO 
RECEIVING SUBSYSTEM 
VMI FOR PREFORMATTED OUTPUT TEXT 


TEXT LENGTH=INPUT LENGTH-42 
MOVE TEXT TO OUTPUT MESSAGE AREA 
RESTORE TOTAL MSG LENGTH 


* QUEUE THE MESSAGE FOR THE INPUT TERMINAL 
CALL FESEND, (OUTMSG) , VL,MF=(E, PARMSAVE) 


LTR R15,R15 
BZ  QUEUED 
LA R10, 12 
B FREEIN 
QUEUED LA R10,0 
* FREE THE INPUT MESSAGE 


FREEIN STORFREE ADDR=(R5) , LEN=(R8) 


* RETURN TO SUBSYSTEM CONTROLLER 


TEST RETURN CODE 
RETURN CODE 12 IF NOT QUEUED 


RETURN CODE 0 IF ALLS WELL 


RTNLINK ADDR=(R13) , LEN=WORKLEN , RC=(R10) 


* 


WORKAREA DSECT LINKAGE WORKAREA, FREED BY RTNLINK 


REGSAVE DS 18F 
COREADDR DS F 
PARMSAVE DS SF 
WORKLEN EQU *-WORKAREA 
INMSG DSECT 
INHDR DS CL42 
INTEXT DS CL200 
OUTMSG DSECT 
OUTHDR ODS OCL42 
COPY MSGHDRC 
OUTTEXT DS CL200 
END 


REGISTER SAVE AREA 
STORAGE MACRO, ADDR OF CORE 
PARAMETER LIST SAVE AREA 


INPUT MESSAGE 
HEADER 
200 CHARACTER TEXT MAXIMUM 
OUTPUT MESSAGE 
HEADER AREA 
HEADER FIELDS DEFINITION 
200 CHARACTER TEXT MAXIMUM 


Figure 17. Echo Message Example; Reentrant Assembler Language 
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3.3.6 Message Switching Between Subsystems 


Any Intercomm subsystem may send a message to any other Intercomm 
subsystem. If a message is sent to some other subsystem, it is called 
"Message switching." An application subsystem can switch a message to 
the Output Utility, which is another subsystem. The Change/Display 
Utility switches messages to the Output Utility. An application 
subsystem may switch (or requeue) a message to itself in the event that 
reprocessing or deferred processing of the message is required. An 
application subsystem may exceed an installation’s core limitations and 
be broken into several subsystems. One subsystem may receive a message 
input from a terminal, perform partial processing and develop 
intermediate results in the form of a message sent to a_ second 
subsystem. The second subsystem processes the intermediate results as 
an input message and may complete the message processing or develop 
additional intermediate results in the form of messages sent or 
switched to any other subsystem or subsystems. Any one of these 
subsystems might also switch messages to the Output Utility. 


Message switching between subsystems is accomplished by moving 
the input message to an output message area and then changing the 
receiving subsystem codes in the header and calling MSGCOL as usual. 
The Verb/Message Identifier (MSGHVMI) may be initialized for 
interpretation by the receiving subsystem. A VMI equal to X’00’ 
indicates that the Edit Utility is to be called by the subsystem. To 
switch messages between terminals, the destination terminal identifier 
(MSGHTID) would also have to be changed, and the VMI set to X’57’. 


3.4 RESTARTED MESSAGES 


After an Intercomm system failure (abend or operator cancel) or 
an operating system failure (requiring a re-IPL of the CPU), Intercomm 
may be brought up in Restart Mode which permits reprocessing of 
messages in progress at the time of failure. Additionally, previously 
cancelled messages (see Figure 14), and unprocessed messages (received 
and queued, but not started) will be requeued for processing after 
system startup completes. This is accomplished by retrieving the 
original input messages from the log created in the previous Intercomm 
execution as described in the Operating Reference Manual, and may be 
coordinated with file or database record backout as described in the 
File Recovery Users Guide and DBMS Users Guide. 


Restarting of messages for a particular subsystem is controlled 
by the RESTART parameter of the SYCTTBL macro defining the subsystem in 


the SCT. A restarted input message (in progress at failure time) 
contains a log code of C’R’ or C’P’ (if data base update may be 
executed by the subsystem). All other input messages contain a log 
code of C’2’ (see Figure 11). A subsystem may need a different 


processing path for a restarted message and should be careful about 
creating an output response message which might confuse a terminal 
operator. 
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322 MVS/XA_ EXTENDED STORAGE LOADING REQUIREMENTS 


If the user desires that an Assembler Language subsystem or 
subroutine be dynamically loaded above the l6meg line under XA or ESA, 
the following is required: 


Programs must be reassembled to ensure that the Release 10 XA 
support versions of macros are used. 


Programs must be coded and defined to Intercomm as reentrant 
and use the linkedit AMODE and RMODE override parameters (see 
Appendix A). 


Subsystems and subroutines must be linked with INTLOAD to 
provide 24-Amode interface to Intercomm. INTLOAD is serially 
reusable (not reentrant), therefore do not link with the RENT 
attribute. 


SYCTTBL macro: code LOADNAM (not SBSP), LANG=RBAL, BLDL=YES 
(default), and REUSE=YES (default) parameters. 


LINKAGE and RTNLINK macros must be used by _ subsystems: 
dynamic save/work area acquired in 24-Amode. 


SUBLINK and RTNLINK macros must be used in dynamically 
loadable subroutines: dynamic save/work area acquired in 
24-Amode. 


If Intercomm service routines (MMU, File Handler, MSGCOL, 
etc.) are called, they may only be accessed via the IBM CALL 
macro using the service routine entry point name (which 
causes a branch to the INTLOAD interface routine which 
handles mode switching on entry and return). The address of 
the routine may not be preloaded from the SPA or SPAEXT. 


Intercomm macros may be used (except the SUBTASK and CALLOVLY 
macros), however the SPA and SPAEXT parameters may not be 
coded, nor may the LINK parameter be used. INTLOAD also 
contains entry points for macro processing (for STORAGE, 
STORFREE, DISPATCH, etc.). The SPA and SPAEXT parameters may 
only be coded on the LINKAGE and SUBLINK macros. The LIST 
parameter .must be used on the STORAGE macro (RENT=NO may not 
be used), and the referenced list must be in 24-Amode storage 
(dynamic save/work area). 


All variable (modifiable) fields and unmodified parameter 
values (ddnames, map names, etc.) passed to Intercomm service 
routines or macros (which branch to Intercomm service 
routines) must be in 24-Amode storage (acquired via LINKAGE, 
SUBLINK or STORAGE macros). That is, ddnames, enqueue names, 
etc. defined in the program as constants (including the 
module name used for MODCNTRL) must be copied to dynamic 
storage before the service routine call or macro execution. 
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Dynamically loadable user subroutines must be defined to 
Intercomm via the SUBMODS macro in the REENTSBS table: code 
LNAME (not NAME), TYPE=BAL (default), BLDIL=YES (default), and 
USAGE=REENT (default) parameters. 


Resident (in Intercomm load module) user subroutines, to be 
called by a program loaded above the l6meg line, must also be 
defined in the REENTSBS table via a SUBMODS macro: code NAME 
parameter only (and USAGE if not reentrant). 


Subsystems (and subroutines) must use the MODCNTRL macro to 
access user subroutines (tables). ACTION=LINK should be used 
for subroutine access so that the Intercomm MODCNTRL 
interface program will handle mode-switching when necessary 
for a loaded subroutine. Parameters passed to a subroutine 
must be in dynamic 24-Amode storage (in case the subroutine 
is resident or loaded in 24-Amode). 


If a MODCNTRL macro with ACTION=LOAD is used, the address of 
the loaded module is returned in register 1 when the issuing 
program receives control back from MODCNTRL. If the hi-order 
bit (80) is on in the address (address is negative), the 


module was loaded above the lémeg line. A program executing 
above the l6meg line may use (branch to) the loaded module 
directly (modes are compatible). A program executing in 


24-Amode must use the XASWITCH macro to switch modes before 
processing the loaded module and again at the end of 
processing before using the MODCNTRL macro with 
ACTION=DELETE. If the address of the loaded module is not 
negative (loaded or resident in 24-Amode), a program 
executing in 31-Amode must immediately execute a MODCNTRL 
macro with ACTION=DELETE and then use a MODCNTRL macro with 
ACTION=LINK, to access the 24-Amode subroutine. A 24-Amode 
table, however, may be processed by a 31-Amode program. 


The 24-Amode interface routine SWMODE must be included in the 
Intercomm linkedit. 


Check the linkedit map of the program to be loaded above the 
lémeg line for unresolved external references that may be 
incorrectly resolved (causing Intercomm to be entered in 
31-Amode) by dynamic linkedit processing, if used. 
References to the SPA (by a hard-coded Vcon) in the SUBLINK, 
LINKAGE and RINLINK macro expansions and by INTLOAD may be 
ignored, as well as references to the BITSECT table by the 
SSSTART, SSSTOP and SSTEST macros. 


Ensure that the following Intercomm interface modules were 
assembled under MVS/XA: SYCT400, DYNLLOAD, MANAGER, INTLOAD, 
SWMODE. 
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4.1 CONCEPTS 


The Message Mapping Utilities (MMU) provide an interface between 
the application subsystem and terminal-dependent message processing 
logic for both input and output messages. MMU is invoked by calls to 
Intercomm service routines which perform mapping functions based upon 
user-specified tables (MAPs). Mapping includes justification, padding, 
and conversion of character data to computational format and vice 
versa. 


4.2 PROCESSING 


MMU input mapping produces fixed length data fields prefixed by a 
two-byte length and one-byte flag (indicates errors or omissions) 
unless the data fields are defined in a structured (named) segment 
(contiguous group of fields). In this case the three-byte prefix 
occurs for the entire segment, not the individual fields. 


MMU output mapping operates upon data in the same format, but the 
flag byte becomes the field (or segment) attribute character. The 
mapped input text area and the unmapped output text area are called 
symbolic maps and are defined by COPY statements in the application 
program’s save/work area. The application program references data 
fields and the associated prefix by symbolic name. For example, a 
customer name field (CUSTMER) of twenty-five characters would appear in 
an MMU symbolic definition as follows: 


CUSTMERL DS XL2 (length) 


CUSTMERT DS xX (flag/attribute) 
CUSTMER DS CL25 (data) 


Output message disposition is determined by options passed to 
MMU. The formatted message(s) may be returned to the subsystem; passed 
to FESEND for terminal queuing; passed to the Page Facility for CRT 
page browsing; or spooled to a DDQ for subsequent transmission as a 
series of report pages for a printer. 


A summary of message processing logic using MMU is shown in 
Figure 18. For a complete description of Message Mapping and its use 


by application subsystems, refer to the Intercomm Message Mapping 
Utilities. 
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APPLICATION SERVICE MAP 
LOGIC ROUTINES FILES 


MAP 


Message zation Modules 


Prepare LOADMAP 
MAPIN Offline 
Call Utilit 


| MAPIN 
Convert/Edit 
Input 
Message 


Process 
Mapped 


Prepare 
Output 
Message 
Data 


MAPOUT 


Message Data 


Prepare 
MAPOUT 
Calling 


Prepare 
MAPEND 
Calling 


MAPEND 
| RETURN Convert/Edit 
Output 


Message 


Figure 18. Message Processing Using MMU 


48 


Chapter 5 


USING THE EDIT UTILITY 


Del CONCEPTS 


The Edit Utility may be used for input messages instead of MMU. 
It provides an interface to facilitate application program logic for 
message editing. When pre-editing has been requested for a verb (via 
Front End Verb Table specification), Intercomm calls the Edit Utility 
to produce edited message text from data fields entered by the terminal 
operator, before queuing the message for the subsystem. Otherwise, the 
BAL subsystem must call the Edit Utility to produce the edited message 
text. Coding format: 


[symbol] CALL EDITCTRL, (input-message,spa,0),VL,MF=(E, list) 
where: 

® input-message is the address of the unedited message. 

e spa is the address of the System Parameter Area. 

e O reserves a third word in the parameter list (used by Edit). 
On return from the Edit Utility, register 15 contains a binary return 
code indicating the results of editing. Zeros indicate the message was 
edited successfully. The address of the successfully edited message is 
in the first word of the parameter list passed to Edit. For a nonzero 
return code, a zero address also indicates the input message was not 


successfully edited (original message freed). Program logic for 
editing an input message: 


LINKAGE - - -,MSG=(R5),SPA=(R3),- - - 
TEST CLI MSGHVMI , X’00' EDIT REQUIRED? 
BNE OKAY NO 


CALL EDITCTRL, ((R5),(R3),0),VL,MF=(E, LIST) 
LTR R15,R15 


BZ GOOD 
RTNLINK - - -,RC=4 UNSUCCESSFUL 
GOOD L R5, LIST EDITED MESSAGE ADDRESS 
OKAY EQU * 


The edited message becomes the input message processed by the 
subsystem. During the course of editing, the Edit Control routine 
strips field delimiter characters such as the system separator 
character (defined in the SPA), 3270 CRT SBA sequences, TAB characters, 
New Line characters, Carriage Return or combined Carriage Return/Line 
Feed, End of Text, End of Message, etc. All other device control 
characters not translated or otherwise suppressed by the Front End 
translation table for a particular device will be treated as text 
within a field. Editing is controlled by the Edit Control Table (ECT), 
which contains all information about each message necessary to perform 
editing. An edit proceeds field by field based upon the user-specified 
ECT. Data fields may be edited by Intercomm or user-coded Edit 
subroutines. For a complete description of the Edit Utility, its 
components and return codes, refer to the Utilities Users Guide. 
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5.2 PROCESSING RESULTS 


The result of processing by EDIT is a message with a standard 
forty-two-byte message header and data fields in one of the following 
basic formats: 


e Fixed Format--each edited field is of fixed length in a 
predefined sequence as follows: 


DATA | DATA DATA 
HEADER 1] 2 N 


e Variable Format--each edited field may vary in length and 
position in the edited result. The PMIFINDB service routine 
(see Chapter 9) may be used to locate specific fields. Each 
edited field is prefixed with a one-byte identification code, 
one-byte length, and possibly a one-byte occurrence number 
for fields defined as repetitive in the ECT: 


DATA DATA DATA 
HEADER] Ij} L ».4 I] L Y Ij L Z 


The Edit Utility considers a message successfully edited if there 
are no required fields (as specified by the Edit Control Table) in 


error or omitted. In the case of unsuccessful editing, Edit sends an 
error message to the originating terminal for each required field 
omitted or in error. If none of the required fields are omitted or in 


error, it remains the responsibility of the application program to 
analyze the edited result and perform recovery logic for any non- 
required fields in error. Figure 19 summarizes results of Edit 
processing for fields in error. 


Field Type 


oS sr a 


Non-Required Field appears in edited result, Field does not 


a Sree ay SS re eens een ee 


Fixed Format 


Variable Format 


= Ss = = SSS eee parengeeeedeeat 
=" = Seen ee ee SN ee 


Field Omitted filled with pad character appear in edited 
associated with Edit Subroutine, result. 


that is, spaces for alphanumeric 
field, zero for numeric field, or 
user-assigned. 


Non-Required Field appears in edited result Field does not 

Field in Error filled with high-values (X'FF’). appear in edited 
result. 

Required Field | Message rejected by EDIT. Message rejected 

in Error or by EDIT. 

Omitted 


Figure 19, Edit Utility Processing of Fields Omitted or in Error 
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6.1 GENERAL CONCEPTS 


The Intercomm File Handler provides centralized control over all 
data file access in the on-line system. Requests for data file access 


are made in message processing subsystems by calling a File Handler 
service routine. 


The correspondence between the normal MVS Data Management Macro 
Instructions and the Intercomm File Handler service routines is shown 
in Figure 20. 


pote perenne soe SSS SST ana ee: = SS SS 


= et — 
= ae SS SS Se ere Sarg ee eee eee Se 


Function BAL Macros Service Routine 
Prepare a file for access SELECT 
Access logical records sequentially GET, PUT , PUTX GET, PUT 
(QSAM ,QISAM) 


Access logical records randomly READ , WRITE READ ,WRITE 
(BISAM, BDAM) 


Access physical blocks (BSAM,BDAM) READ , WRITE READ , WRITE 


Access VSAM files GET GETV 
PUT PUTV 


Conclude file access CLOSE RELEASE 


Figure 20. Functions of File Handler Service Routines 


A data file on-line is identified to the File Handler by the 
existence of a data definition (DD) statement in the execution JCL. 
Files must be existing (DISP=OLD or SHR) except for sequential output 
data sets (DISP=NEW or MOD). 


DD statement requirements are illustrated in Figure 21. 
Additional requirements for VSAM are described in that section. 
Special processing definitions for particular files are defined to 
Intercomm at system startup by FAR (File Attribute Record) parameters. 
These include READONLY (prohibit output), OPEN (at startup), file 
duplexing, etc., and are described in the Operating Reference Manual. 
Additional parameters for file recovery (in case of program or system 
failure) are described in the File Recovery Users Guide. 
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//ddnamex DD DSNAME=** 
, DISP=** 
, DCB=(DSORG=** 
, OPTCD=** For BSAM,BDAM,BISAM only. 
,» RECFM= Must be specified by existing 
, BLKSIZE= data set label or explicitly 
in DD statement. 


*Name used to identify file in calls to SELECT. 
**Marks those parameters which must be explicitly specified on the DD 
Statement for each data set. 


Figure 21. DD Statement Parameters for the File Handler. 


In centralizing data file accesses, the File Handler provides one 
central set of control blocks for each file, thus reducing core 
requirements in individual message processing subsystems. 


Furthermore, all the facilities of the following Operating System 
Data Management functions are accessible to any subsystem: BDAM, BSAM, 
QSAM, BISAM, QISAM and VSAM. 


The File Handler also supports the following ISAM replacement 
access method available from another vendor: IAM. 


Data Base interfaces supported under Intercomm (IDMS, ADABAS, 
TOTAL, DL/I, Model 204, System 2K) are described in the DBMS Users 
Guide and the respective vendors’ manuals. 


6.1.1 Subsystem Processing 


In the on-line environment, several subsystems in concurrent 
execution may require access to the same data file. Rather than each 
subsystem issuing an OPEN and corresponding CLOSE for accessing a 
particular file, the File Handler will open a file the first time it is 
accessed (unless already opened at startup) and the file remains open 


for the duration of the on-line job in execution. A SELECT request 
simply establishes internal control blocks and the corresponding 
RELEASE request merely disconnects those internal control blocks. In 


each subsystem, following a SELECT for a particular file, access 
functions (READ, WRITE, GET, PUT, GETV, PUTV) may be called as many 
times as may be necessary for message processing logic. RELEASE must 
be called for each selected file prior to the RTNLINK to the System 
Monitor. 
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Each subsystem must provide space for two File Handler control 
areas. The information in these areas is unique for each message 
thread, so they must be defined in the dynamic save/work area of 
reentrant programs. 


For each call to a File Handler service routine, the File Handler 
is passed the addresses of the two control areas, as illustrated in 
Figure 22. The first is a full word aligned 12-word (48 bytes) area, 
called an External DSCT (EXTDSCT), which the File Handler uses to save 
control information for the subsystem processing thread, from the time 
that a given file is first SELECTed until it is finally RELEASEd. A 
unique EXTDSCT must be defined for each file concurrently accessed 
within the same processing thread and should be cleared to zeros before 
calling SELECT. The other control field, called the File Handler 
Control Word (FHCW), is an aligned full word field used for 
communication between the File Handler and the calling subsystem. 
Prior to each call to a service routine, the subsystem must clear the 
FHCW with blanks or initialize it with a predefined request code as 
described for each routine. A code of space (blank) is indicated in 
the detailed access descriptions by the lower case letter }f. An 
example of such a request would be to establish Exclusive Control 
during a call to READ with intent to update. The File Handler will 
return a completion code in this word, after servicing a request, to 
communicate the status of the operation back to the subsystem. 


*FILE HANDLER CONTROL AREAS 

* 

FILEAREA EXTERNAL DSCT 

FHCW FILE HANDLER CONTROL WORD 


FHSTATUS STATUS -BYTE 
FHREQ REQUEST- BYTE 
FHREST UNUSED (except for VSAM) 
: I/O AREA DEFINITION might 
follow 


Figure 22. Defining File Handler Control Areas 


6.2 CALLING SERVICE ROUTINES 


A reentrant Assembler Language subsystem calls a File Handler 
service routine using the following format: 


[symbol ] CALL function, (parameters) ,VL,MF=(E, list) 


where: 


e function is the specified File Handler routine being 
accessed, such as SELECT, READ, etc. 
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@ parameters are the parameters passed to the File Handler for 
each specific routine 


e VL indicates a variable-length parameter list, as illustrated 
in the description for each File Handler function 


e MF=(E,list) indicates the executable form of the macro 
instruction with the parameter list saved at the location 
labeled ‘list’. ‘list’ must be defined in the dynamic 
storage area unique to each processing thread in order to 
maintain reentrancy. 


The parameters for the File Handler service routines are 


described in Figure 23, The specific parameters passed to a given 
service routine depend on file requirements and the processing options 


of 


the particular service routine called. If the calling subsystem (or 


subroutine) might be loaded above the l6meg line (under XA or ESA), 
then all parameters must be in the dynamic save/work area (or other 
area acquired in 24 Amode). 


aang oo 
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Parameter Content 


EXTDSCTname A 48-character fullword-aligned area supplied by the 
subsystem for the File Handler’s use for each file 
SELECTed 

FHCWname The 4-byte File Handler Control Word, in which the 
File Handler returns a completion code to the 
subsystem (see Figure 22) 

ddname An eight-character constant containing the name of the 
DD statement describing the data set to Intercomm 

Record-area The area for data read from, or to be written to, 
the file 

Key The key for file access (ISAM, Keyed BDAM, VSAM-KSDS) 

VSAM RBA Four-byte Relative Byte Address number (ESDS) 

VSAM RRN Four-byte Relative Record Number (RRDS) 

Block-ID Applies only to BDAM files: 
e three-byte relative block number (RBN) 
e three-byte relative track and record number (TTR) 
e eight-byte actual address (MBBCCHHR) 

Figure 23. File Handler Service Routine Parameters 


The File Handler IAM support uses the Intercomm ISAM support routines. 


54 


Chapter 6 Using the File Handler 


On return from a File Handler service routine, the leftmost 
position of the FHCW area will contain a character indicating the 
result of the operation, as shown in Figure 24. Additionally, for VSAM 
files, the rightmost position of the FHCW will contain a VSAM reason 
code. 


Hardware I/O error 


Unusual condition (EOF, invalid key, etc.) 


Exclusive control time-out occurred 
Not used 


Invalid request (no DD statement, invalid 
parameter sequence, attempt to output to an input 
only file, etc.) 


Figure 24. Outline of File Handler Return Codes 


The application subsystem logic must then analyze this return 
code and take appropriate error recovery action. An error message 
might be created and queued for output to the terminal. Otherwise, the 
subsystem can return to the Subsystem Controller with a return code of 
12, indicating that the Subsystem Controller should call the USRCANC 
routine which in turn will send an error message to the terminal. 


6.2.1 Automatic Error Checking 


If the application subsystem logic is such that special error 
recovery processing is not required, the File Handler will perform 
error checking itself and data will be returned to the subsystem only 


if the return code is zero. Otherwise, the File Handler will force a 
program check, which causes cancelling of the input message and return 
to the Subsystem Controller, which calls the USRCANC routine. To 


request this function, place a character 'C’ in the first byte of the 
FHCW prior to calling a File Handler service routine. 
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6.3 SELECT, RELEASE FUNCTIONS 


SELECT must be called to initialize the subsystem’s EXTDSCT prior 
to any data access function performed by the File Handler. Prior to 
the call to SELECT, the subsystem’s EXTDSCT must be initialized to 
binary zeros. 


RELEASE must be called to notify the File Handler that its 
pointers to the subsystem’s EXTDSCT should be cleared and that all data 
access to a particular file within one subsystem thread is complete. 
There must be a RELEASE corresponding to each SELECT of a file. 
Multiple SELECTs of the same file using the same EXTDSCT are not 
permitted without intervening RELEASEs, within the same processing 
thread. After each RELEASE, the EXTDSCT should be cleared to zeros 
before being reused. 


Coding format: 
[symbol] CALL SELECT, (EXTDSCTname , FHCWname , ddname) , VL,MF=(E, list) 
[symbol] CALL RELEASE, (EXTDSCTname , FHCWname) ,VL,MF=(E, list) 

Note: the ddname must be in the dynamic save/work area if the calling 


subsystem (subroutine) can be loaded above the l6meg line under 
XA or ESA. 


Figure 25 describes the return codes for SELECT and RELEASE. 


a a a EN ey meow sa ae ema, sana en 


SELECT RELEASE 


A reusable file (disk input) ready Successful 
for access; sequential access begins release 

at first record. 

A nonreusable file (SYSOUT, disk Not applicable 
output (DISP=NEW/MOD or DISP=SHR/OLD 


| and FAR WRITEOVER parm specified, or 
a data set on tape) ready for access, 
begins after last record previously 
accessed. 


No ddname found in File Handler File not 
internal control table. (No DD selected. 
statement in JCL or the file has 

been "locked" by the FILE control 

command. ) 


Figure 25. File Handler SELECT/RELEASE Return Codes 
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6.3.1 Closing a File 


Occasionally, it is necessary to close a file, perhaps because it 
is to be updated by a batch job. A special form of RELEASE requests 
the File Handler to close a file. However, unless some external 
control is taken to assure that no other programs have selected the 
file, a close request could cause other transactions for the file to 


fail. Also, if new transactions are attempting to access the closed 
file, the File Handler will open it again and unpredictable results may 
occur. Intercomm provides the FILE system control command for 


systemwide file access control. 
To close a file from an application subsystem: 


e If the file has been previously selected: first release the 
EXTDSCT by calling RELEASE referencing the EXTDSCTname used 
when the file was selected (as described above), then 


® Move a character C to the second byte of the FHCW ('PCHpp') 
and call RELEASE supplying the ddname of the file to be 
closed; use the following coding format: 


[symbol] CALL RELEASE, (ddname , FHCWname) , VL,MF=(E, list) 


6.4 EXCLUSIVE CONTROL FOR NON-VSAM FILES 


In a multithread environment with only inquiry applications, the 
fact that several message processing programs may concurrently retrieve 
data from the same file or files presents no operational problems. 
However, when more than one message processing program attempts to 
update or add records to a file, data integrity problems can occur. 
Figure 26 illustrates the problems of concurrent updates; program B's 
update nullifies that of program A. Exclusive control implies that 
while one program is operating on a record, that is, the time between a 
READ and a WRITE, all other requests to read or write that particular 
record will be delayed. A program requesting a record held during 
exclusive control by another program is not notified of this delay, but 
rather stops execution in the File Handler until exclusive control is 
either removed or expires so that the File Handler can then proceed 
with the requested function. Exclusive control, when required, must be 
requested separately with each call to File Handler READ or GET 
functions. Exclusive control for basic access methods operates at the 
block or record level. Exclusive control for queued access methods 
operates at the data set level; thus applications should be designed to 
avoid GET for update whenever feasible. 


To obtain exclusive control over the entire data set in a QISAM 
file or over a physical block in a BDAM or BISAM file, move ‘PxX}Pp' to 
the File Handler Control Word prior to calling GET or READ. Exclusive 
control does not apply to physical sequential (QSAM/BSAM) files. 
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Figure 26. 
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Exclusive control will be released by: 


e A call to WRITE or PUT referencing the same EXTDSCTname, that 
is, the update of the previously acquired record, and no key 
or block-id specified. 


e A call to WRITE referencing the same EXTDSCTname and a key 
and/or block-id is specified. 


e A call to READ or GET referencing the same EXTDSCTname 
(retrieving a new record from the file). 


e A call to RELEASE referencing the same EXTDSCTname. 


e An elapsed time after the call to READ with Exclusive Control 
greater than the exclusive control time-out value of the File 
Handler. This is set at two minutes for any given record and 
a maximum of ten minutes for consecutive exclusive accesses 
to a QISAM file. 


NOTE: A return code of 3 after a call to WRITE or PUT to 
update a record held in exclusive control indicates 
that exclusive control timed out: the WRITE or PUT 
did not take place. The program should re-READ or 
re-GET the same record with exclusive control and 
WRITE or PUT again. 


e A call to RELEX, if the program logic is such that the record 
does not need to be updated, or additional and time-consuming 
activity (accessing other files) is required before resuming 
access to the file. Such a program could call RELEX to 
release exclusive control without actually RELEASEing the 
file until later in the program logic. 


6.4.1 Release Exclusive Control --RELEX 


RELEX is called to release Intercomm or VSAM exclusive control 
without having to read, update, time-out, or RELEASE the file. 


Coding format: 


[symbol] CALL RELEX, (EXTDSCTname , FHCWname) ,VL,MF=(E, list) 


Return Code 


= ——— = oe —————— 


Meaning 


Exclusive control released 


File not selected or invalid function 


Figure 27. File Handler Release Exclusive Control (RELEX) 
Return Codes 
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6.5 SEQUENTIAL ACCESS METHOD PROCESSING 


6.5.1 File Handler Service Routines--GET, PUT SAM): READ, WRITE 
(BSAM) 


GET is called to access the next sequential logical record from a 
file. PUT is called to write the next sequential logical record to a 
file. READ is called to access the next sequential physical block. 
WRITE is called to write the next sequential physical block. If PUT-or 
WRITE is called referencing a disk data set, the record last accessed 
by a GET or READ will be updated, however, the length may not be 
changed. GET processing is subtasked by the File Handler in order to 
provide multithreading facilities; for further details, see the 


Operating Reference Manual. 


Coding format: 


[symbol] CALL GET, (EXTDSCTname , FHCWname , record-area 
[,record-length]) ,VL,MF=(E, list) 


[symbol] CALL PUT, (EXTDSCTname , FHCWname, record-area 
[,record-length]) ,VL,MF=(E, list) 


[symbol] CALL READ, (EXTDSCTname , FHCWname, record-area 
[,record-length] ),VL,MF=(E, list) 


[symbol] CALL WRITE, (EXTDSCTname , FHCWname ,record-area 
[,record-length]) ,VL,MF=(E, list) 


Es ee es pipe = TEE ns NET GEAR tg ee Pa a perenne treme eee eerie ei Se eT TT ne 


"Return Codes GET, ‘PUT, WRITE 
a ae | 1/okrror = =—Ss—(“<ité‘édd ORO, UU 
er en | End-of-file +~—*«| (Not applicable) 2” 


| Not selected or invalid | Not selected or invalid 
function; that is, using | function; that is, using a 
an output-only file tape input file or readonly 

file, or file not sequential. 


* For WRITE to a disk file: indicates End-of-file (write not done) 


Figure 28. File Handler Sequential Access Method Return Codes 
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6.5.2 Undefined Record Format and Record Length 


The record-length parameter is valid and required only when a 
file with an undefined record format (DCB=RECFM=U) is accessed. The 
record-length parameter points to a fullword containing the length of 
the output record before a PUT or WRITE operation, or to contain the 
length of the input record after a GET or READ operation. The second 
character of the File Handler Control Word must be set to U to utilize 
this feature. Do not code the DCB subparameter LRECL on the DD 
statement for the file in the Intercomm execution JCL. The BLKSIZE, 
RECFM and DSORG subparameters are required. 


6.5.3 Variable-Length Record Format and Record Length 


Variable-length records start with a Record Descriptor Word (RDW) 


which must be fullword aligned. The first two bytes of the word 
contain the record length in binary (+4 for the RDW); the second two 
bytes contain binary zeros (low values). The RDW is’ followed 


immediately by the record data, and must be recognized by the subsystem 
on input, and provided and initialized on output. 


For blocked files, if GET or PUT are used, the access method will 
perform the blocking and deblocking. If READ or WRITE are used, the 
application program must perform the deblocking (READ) and blocking 
(WRITE). In this case, the block must start with a Block Descriptor 
Word (BDW) of four bytes (aligned); the first two bytes contain, in 
binary, the total block length (including 4 for the BDW), and the 
second two bytes contain binary zeros (low values). For JCL details, 
and FAR options for defining and accessing the file, see the Operating 
Reference Manual. 
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6.6 INDEXED SEQUENTIAL ACCESS METHOD PROCESSING 


To use an ISAM file on-line under Intercomm, do not define three 
DD statements (INDEX/PRIME/OVERFLOW) for either the off-line creation 
of the ISAM data set, or the on-line execution DD statement. For 
creation, let the access method set up the index and overflow areas 
(use CYLOFL parameter on DD statement). For on-line execution, define 
only DISP=OLD and the data set name, volser and unit parameters if not 
catalogued, and the DCB parameter DSORG=IS. Optionally, the DCB 
parameter OPTCD may also be specified. See also the descriptions of 
FAR parameters applicable to ISAM data sets described in the Qperating 
Reference Manual. 


6.6.1 File Handler Service Routines--GET, PUT (QISAM); READ, WRITE 
(BISAM) 


GET is called to access the next sequential record, or to 
reposition (if a key is specified) and access the next sequential 
record. READ is called to retrieve a specific record at random. PUT 
is called to update the last record retrieved by a call to GET. WRITE 
is called to update the last record retrieved by a call to READ, or to 
add a record to the file (if a key is specified). For update, 
exclusive control may be requested; otherwise use blanks in the FHCW. 


Coding format: 


to retrieve next sequential record: 


[symbol] CALL GET, (EXTDSCTname , FHCWname, record-area) , 
VL,MF=(E, list) 


to reposition and retrieve record with key equal or high: 


[symbol] CALL GET, (EXTDSCTname , FHCWname ,record-area,key) , 
VL, MF=(E, list) 


to update last GET: 


[symbol] CALL PUT, (EXTDSCTname, FHCWname,record-area), 
VL,MF=(E, list) 


to retrieve a specific record: 


[symbol] CALL READ, (EXTDSCTname, FHCWname , record-area,key) , 
VL,MF=(E, list) 


to update last READ: 


[symbol] CALL WRITE, (EXTDSCTname, FHCWname, record- area) , 
VL,MF=(E, list) 


to add a specific record: 


[symbol] CALL WRITE, (EXTDSCTname , FHCWname, record-area,key), 
VL,MF=(E, list) 
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Figure 29 describes return codes for ISAM access. 


el a iy Er ears SSS oa —— ee 


Record with equal Record from 
or next higher previous GET 


key retrieved updated 


End of File 
N/A Exclusive Control 
Time-out 

File not selected 
or invalid function 


File not selected File not selected 
or invalid function]! or invalid function 


BISAM 
Return 
Codes WRITE w/o Key 
0 Record from Record with equal 
previous READ specified key key retrieved 
updated added 
1 I/O error I/O error 
Z N/A Key already exists 
or no room to add 
new record 
3 Exclusive Control 
Time-out 
9 File not selected File not selected File not selected 


or invalid function] or invalid function] or invalid function 


Figure 29. File Handler ISAM Return Codes 
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6.7 DIRECT ACCESS METHOD PROCESSING 


BDAM files are accessed by block-id. The form of the block-id 
is defined in the OPTCD subparameter of the DCB parameter of the DD 


Statement and the same form must be used by all programs accessing the 
file: 


e OPTCD=RF--block-id is three-byte binary RBN (relative block 
number) for fixed-length files only 


e OPTCD=AF--block-id is eight-byte actual MBBCCHHR 


e OPTCD=F--block-id is three-byte binary TIR (relative track 
and record number) for fixed- or variable-length files. 


The F permits feedback (of block-id) requests: the form of the 
block-id is that requested by the OPTCD parameter. For Keyed BDAM with 
extended search, insert an E immediately after the = sign (that is, 
code OPTCD=ERF, etc.), and specify the LIMCT subparameter on the DCB 
parameter of the DD statement. 


6.7.1 File Handler Service Routines--READ, WRITE (BDAM) 


READ is called to retrieve a physical block. WRITE is called to 
update a block previously read, to replace an existing block in a 
preformatted file, or to add a new block. 


Coding format: 


[symbol] CALL READ, (EXTDSCTname, FHCWname,record-area[,key], 
block-id) ,VL,MF=(E, list) 


[symbol] CALL WRITE, (EXTDSCTname , FHCWname, record-area[,key] 
[, block-id]),VL,MF=(E, list) 


Figure 30 shows FHCW options (byte 2) for standard and keyed BDAM 
files, and when to use key and/or block-id fields. Figure 31 describes 
the corresponding return codes. When reading a keyed BDAM file, the 
key will be read into the key field if a key parameter is passed and 
the key is not used as the search argument (w/o extended search). For 
a keyed BDAM file, replace requires a previous read; update and replace 
are synonymous. 


Intercomm provides two utilities for off-line preformatting of 
fixed-length BDAM files: 


® CREATEGF for BDAM files without keys 
e KEYCREAT for BDAM files with keys. 


These utilities are described in the Operating Reference Manual. 
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1. BDAM Files Without Keys 


Request Macro 
READ w/o exclusive control, w/block-id READ DIF 
READ w/exclusive control, w/block-id READ DIX 


WRITE to update last READ, w/o block-id WRITE DI/DIX 


WRITE to update/replace w/o previous READ, WRITE DI 
w/block-id 
WRITE to add a record--variable-length only WRITE DAF 
(record address returned automatically in 
caller's block-id field) 

2. BDAM Files With Keys 

Request Macro 

READ data block only w/o exclusive control READ DKF 
(w/extended search) w/key, w/block-id 
READ data only w/exclusive control READ DKX 


(w/extended search) w/key, w/block-id 


READ key and data block w/o exclusive control READ DIF 
w/o extended search, w/block-id (w/key) 


READ key and data w/exclusive control READ DIX 
w/o extended search, w/block-id (w/key) 


WRITE to update data only w/o extended search WRITE DKF/DKX 
w/key 


WRITE to update key and data w/o extended WRITE DI/DIX 
search, w/key 


WRITE to add a record--next available space WRITE DAF 
w/key, w/block-id (w/extended search) 


*Feedback of record addresses may be requested for these options only 
by placing an F in byte 3 of the FHCW. 


Figure 30. File Handler BDAM Option Codes. 


NOTE: The DI form of the macros (issued in the File Handler) 
requires that the block-id field contains the exact address of 
the data record in the form specified by the OPTCD 
subparameter on the DD statement. With the DK form, if 
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extended search is not specified (via E on the OPTCD subparameter), 
only one track is searched for a record with key matching that passed 
in the key field, and starting at the address specified in the block-id 
field. A WRITE for update of last READ does not need a block-id, as 
positioning is remembered internally. 


1. BDAM Files Without Keys 


WRITE w/block-id 
Block retrieved Block from previous | Specified block 
READ updated added/replaced 


I/O error I/O error 


Block out of range | N/A RECFM=F... 
Block out of range 


No space available/ 
block out of range 
Exclusive Control N/A 

Time -Out 
File not selected File not selected File not selected 
or invalid function] or invalid function | or invalid function 


. BDAM Files With Keys 


WRITE w/o block-id 
Record from 
previous READ 
updated 


I/O error I/O error 
Key not found Key not found at RECFM=F... 
(READ w/key) block-id saved from | No dummy record found 
previous READ ~~ ---------------+--------- 
(WRITE DK only) 


WRITE w/block-id 


ee a 


Logical record 
retrieved 


Specified record 
added 


File not selected File not selected File not selected 
or invalid function] or invalid function | or invalid function 


Figure 31. File Handler BDAM Return Codes 
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6.8 VIRTUAL STORAGE ACCESS METHOD (VSAM) PROCESSING 


VSAM support is provided for all three file types: kKSDS, ESDS, 
and RRDS. Subsystems designed to access VSAM files use two File 
Handler service routines; GETV and PUTV. SELECT and RELEASE function 
for VSAM as they do for OS data sets. Calls are similar to the 
standard File Handler format, with the File Handler Control Word (FHCW) 
used to specify VSAM options. DD statements for VSAM must specify 
AMP=(AMORG) and for fixed-length data records, ‘RECFM=F' must also be 
specified on the AMP parameter: AMP=(AMORG, '’RECFM=F’ ). FAR options 
and execution options for VSAM files such as LSR buffer pool support, 
empty ESDS file load or overwrite, and data set name sharing, are 
described in the Operating Reference Manual. Most users converting 
ISAM to VSAM can continue to use their current File Handler calls. 
Refer to "ISAM/VSAM Compatibility under Intercomm" later in this 
chapter for further details. 


6.8.1 File Handler Service Routines--GETV, PUTV (VSAM) 


A VSAM call may request either sequential or direct access and 
may specify access for KSDS via keys (keyed access) or for ESDS via 
Relative Byte Addresses (addressed access). A keyed access call for 
direct retrieval may provide either a generic key or a full key, and 
may specify a search for either an equal (generic) key or for the first 
greater-or-equal (generic) key. 


A VSAM Relative Record Number Data Set (RRDS) may be accessed 
sequentially, or directly by Relative Record Number. A direct access 
request to a RRDS is made by suppling the Relative Record Number of the 
desired record instead of a key or RBA. All direct accesses to an RRDS 
must specify "full key, search equal." RBA access is not allowed and 
RRNs should not be converted to RBAs for access to an RRDS. Records 
may be inserted into emply slots in an RRDS but a record may not be 
added with a higher relative record number than the maximum allowed. 
This maximum is specified when the data set is defined to VSAM. 


GETV calls are processed assuming that no update will be 
performed unless the caller so specifies. The caller may switch back 
and forth from direct to sequential access, provided VSAM rules are not 
violated, for example, keyed request against an entry-sequenced data 
set. The File Handler service routine GETV is called for retrieval. 
The File Handler service routine PUTV is called for storage or 
deletion. 


Coding formats: 


For sequential access 


[symbol] CALL GETV, (EXTDSCTname , FHCWname, record-area), 
VL,MF=(E, list) 
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Coding formats (continued): 
For direct access 


[symbol] CALL GETV, (EXTDSCTname , FHCWname, record-area, (rba}), 


VL,MF=(E, list) (key) 
{rrn} 
For update of record retrieved by preceding GETV or for sequential 


addition 


[symbol] CALL PUTV, (EXTDSCTname , FHCWname, record-area), 
VL,MF=(E, list) 


For direct addition of a new record 


[symbol] CALL PUTV, (EXTDSCTname , FHCWname, record-area, {rba}), 
VL,MF=(E, list) {key} 
{rrn} 


where: 
EXTDSCTname is the standard File Handler parameter. 
FHCWname is the standard File Handler parameter. Its VSAM use is 


to define processing options and to return completion codes to 
the caller (see Figures 32 and 33). 


record-area is the label of the user’s I/O area. For fixed 
length records, no length is specified and data will start in the 
beginning of the area. For variable length records, the first 


four bytes of the area are used as an OS-type, fullword-aligned, 
variable record descriptor word (RDW), the first two bytes of 
which specify the appropriate length in binary (data length +4); 
data begins in the fifth byte. For GETV, the File Handler will 
return this length to the caller and for PUTV, the caller must 
provide the length to the File Handler. 


rba is the label of an aligned fullword containing the Relative 
Byte Address when required for addressed access. 


key is the label of a field providing a key, when required for 
keyed access.. If a generic key is provided, then the first two 
bytes of this field must be the length, in binary, of the generic 
key which must begin in byte 3, and the field must be 
fullword-aligned. 


rrn is the address of a fullword-aligned field providing a 


four-byte binary Relative Record Number whose value is 1 to n, 
where n is the maximum record number defined for the data set. 
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| 6.8.2 VSAM Processing Options 


The following determine the mode of VSAM access to be performed: 


e The preceding call 


A VSAM call is dependent upon the preceding call only in two 
cases: PUTV for update, or sequential GETV or PUTV calls 
requiring initial positioning. 


In the first case, the PUTV call must be immediately preceded 
by a GETV for update, which identifies the record to be 
updated. The PUTV for update has no fourth parameter because 
the key, RRN or RBA was defined by the prior GETV. In the 
second case, a direct call providing a key, RRN or RBA and 
requesting positioning must be issued in order to process 
sequentially starting from that point in the file. To 
request positioning in this manner, specify S in the second 
byte of the FHCW for the direct call to GETV; the first 
record in the sequence will be returned. For an ESDS file, a 
GETV call without a fourth parameter results in sequential 
reads from the beginning of the file; the S in the FHCW is 
unnecessary. 


e The presence or absence of the fourth parameter 


With the exception of a PUTV for update, all calls for direct 
access specify a fourth parameter and all subsequent calls 
ws for sequential access specify only three parameters. 


e The contents of the File Handler Control Word 


The second and third bytes of the FHCW are used to complete 
the definition of the options desired. Alphabetic codes are 
used and positive tests are made for each defined code. When 
no defined code is present, the default option (blank) is 
used. 


Bytes 1 and 2 of the FHCW are utilized the same as for OS Access 
Methods for Return Codes (Byte 1) and Special Requests (Byte 2). The 
first byte of the FHCW will contain a zoned decimal digit upon return 
from GETV or PUTV. A nonzero value indicates an error or an 
exceptional condition. 


Byte 2 is used in conjunction with direct access. When an S is 
provided in byte 2, the direct access is treated as the first of a 
series of sequential requests which begins at a point specified by the 
fourth parameter. Therefore, a VSAM POINT will be issued and 
sequential access will subsequently be performed for the next call. 
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Byte 3 is used for all VSAM calls as illustrated in Figure 32. 
There are five default (blank) cases: 


e GETV with three parameters (subsequent sequential access) 
e@ GETV with four parameters (search key/RRN equal, no update) 


e PUTV with three parameters with no prior GETV for update 
(sequential add/insert) 


e PUTV with three parameters and with a prior GETV for update 


e PUTV with four parameters (direct key/RRN add/insert) 


6.8.3 FHCW Reason Codes for VSAM 


Byte 4 is used to provide VSAM reason codes (from the RPL 
feedback field) upon completion of a VSAM file access request. In 
VSAM, a distinction is made between logical and physical errors. In 
either case VSAM returns a supplementary reason code in hexadecimal 
defining the condition more precisely. Accordingly, the File Handler 
will return this reason code in FHCW byte 4, for the caller's use. If 
the File Handler was called at an ISAM entry point (GET/PUT, 
READ/WRITE), the code returned in FHCW byte 1 may differ from GETV/PUTV 
calls (in order to maintain compatibility with existing ISAM 
subsystems). Figure 33 summarizes VSAM and ISAM/VSAM return codes. - 
VSAM reason codes are fully documented in IBM’s VSAM Administration : 
Guide. 


6.8.4 Exclusive Control for VSAM Files 


VSAM automatically provides exclusive control of a control 
interval (physical block) whenever a GETV for update is processed if 
the file was defined with SHAREOPTION 1 or 2. The subsystem must 
release this exclusive control via a call to RELEX before another GETV 
is issued for the same file, unless an intervening PUTV for update or 


erase is issued. If no subsequent GETV will be issued, the call to 
RELEASE will also release exclusive control. There is no VSAM 
exclusive control time-out. If the VSAM file is accessed by more than 


one region (Intercomm and/or batch), see IBM documentation on VSAM 
SHAREOPTIONsS, and the Intercomm Operating Reference Manual. 
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‘ 6.8.5 Alternate Path Processing of Keyed VSAM Files 


Base Cluster and Alternate Path processing of keyed VSAM files is 
supported with the following (VSAM-imposed) restrictions: 


® If defined in the JCL, the DD statement for the base cluster 
must be before those for any related paths, and open at 
startup must be requested via a FAR. Also, both the base 
cluster and the paths must be connected to an LSR buffer 
pool. 


e Each path to be accessed on-line must be defined in the JCL 
and be SELECTed with the corresponding ddname. When created, 
the path must be defined with the UPDATE option. 


e The FAR READONLY option must be specified for all paths and 
the base cluster (if defined) except for the path used for 
updating, when Shareoption 2 is in effect for the base 
cluster. If updating is only via the base cluster, then 
READONLY must be specified for all associated paths. VSAM 
will not allow any accesses to a base cluster under 
Shareoption 1 when one path has opened it for update. A base 
cluster under Shareoption 3 may be accessed for reads or 
updates by more than one path at any time, however no 
exclusive control (read/write file integrity) is provided by 
either VSAM or Intercomm. For Intercomm-provided exclusive 


control for Shareoption 4, see the Operating Reference 
Manual. 


® If multiple paths are accessed, and/or retrieval/update is 
done via the path(s) and the base cluster, retrieval of 
updated versions of the records can be ensured via the FAR 
DSN and LSR parameters. 


e Since duplicate keys may occur in an Alternate Index, the 
application program is responsible for checking for duplicate 
keys. Sequential processing (GETV type 1) can be used after 
the first GETV with key (and an S in byte 2 of the FHCW) in 
order to retrieve subsequent records. The program can test 
to see if the last record under a duplicate key was retrieved 
by checking the VSAM reason code which will be placed in byte 
4 of the FHCW. See the IBM VSAM Administration Guide for 
reason code values. 


e The alternate index data set must be defined with the UPGRADE 
attribute and be built prior to Intercomm startup. An 
attempt to retrieve a record from an empty file will cause a 
program check, 


e Alternate index data sets should not be defined in the JCL 
unless access to a data record containing the prime keys is 
desired, or path processing is not used. Only readonly 
processing should be done for an AIX and for any related 
paths and for the base cluster, otherwise, retrieval of the 

C current version of a record is unpredictable. 
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Figure 32. 
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Key or = (not valid 
for RRDS) 

Generic | Search = 

Key (not valid for 
RRDS ) 

Generic | Search greater 

Key or = (not valid 
for RRDS) 

RBA Addressed Access 


No prior GETV for 
update (insert 
not allowed for 
Addressed Access) 
Prior GETV for 
update 

(addressed update 
may not change 
length) 

Prior GETV for 
update (not 
permitted for 
addressed access) 


Key or (no prior GETV) 
RRN 
RBA {Insert not valid 


File Handler VSAM Call Summary 
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venti 


= eS 


Condition at Completion of Operation* 


Successful completion (A) 04,08,0C,10,1C 


04 ,08,0C,10,14,18 


Physical I/O error (A) 


End of data (1, 2) 


No record found (3, 4, 5, 6, 7) 


Key not within defined key ranges 
(3, 4, a; 6, 7) 


Duplicate key (8, 11) 


Update attempt with new key (9) 
Key exceeds maximum (5, 6) 


Addressed update changes length (9) 


Invalid RBA provided (7, 12) 
Required positioning not performed 
(1, 2, 8) 
Direct or update call while loading (8) 
GETV for ESDS while loading (2,7) 
Insufficient disk space (8, 9, 11, 12) 
Record on unmountable volume 
(1-7, 11, 12) 


Invalid Relative Record Number (3,11) 


Invalid RBA access to a RRDS file (7,12) 


*Characters in parentheses reference the type(s) of VSAM Call 
(Figure 32) which apply. A = all cases. 


**Should not occur. The File Handler will force a program check 
condition to terminate the message in progress. 


Figure 33. File Handler VSAM Return and Feedback Codes 
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6.9 LSAM/VSAM COMPATIBILITY UNDER INTERCOMM 


Subsystems accessing ISAM files can function with little or no 
modification when their files are converted to VSAM. Intercomm's 
ISAM/VSAM interface does not use IBM's VSAM/ISAM interface modules. 
See the Operating Reference Manual for steps necessary to activate the 
interface. When processing a VSAM data set, the File Handler uses 
QISAM compatible access for a GET or PUT call and BISAM compatible 
access for a READ or WRITE call. 


An ISAM retrieval is converted to a VSAM GET for update. If a 
key is provided, it is, of course, treated as a full key. For GET with 
a key, positioning and a search for a greater or equal key is 
performed. For READ, a search is made for an equal key. File Handler 
logic will initialize the user FHCW prior to performing the VSAM 
function as follows: 


e Byte 2 is set to ’S' to force sequential positioning. 
e Byte 3 is set to 'U' or 'L’ to force update mode. 


ISAM delete code processing continues to function as usual via 
the OPTCD subparameter of AMP on the DD statement. The new OPTCD 
parameters (I, IL) which specify supplementary delete code processing 
are supported also. 


The following considerations apply to ISAM users converting to 
VSAM and should be carefully observed: 


@ ISAM subsystems must be operational when accessing ISAM 
files. Erroneous ISAM parameter lists will cause 
unpredictable results. 


® Between a SELECT and a RELEASE, neither READ and GET nor 
WRITE and PUT may be intermixed. 


@e The caller may not provide his own DCB. 


r The FHCW will be modified in order to convert the call to its 
VSAM equivalent. 


e There is no equivalent to a QISAM physical block once the 
file has been converted to VSAM. All VSAM data records are 
equivalent to ISAM logical records. This means that users 
processing the file via READ in one subsubsystem and GET in 
another will both retrieve what would have been an ISAM 
logical record. 


Figure 33 describes return codes when ISAM/VSAM compatibility is 
used, 
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USING THE OUTPUT UTILITY 


Tak CONCEPTS 


The Output Utility is a subsystem that processes messages 
destined for terminals operating under control of Intercomm. It is 
responsible for completing any device-dependent formatting requirements 
in a message before passing it to the teleprocessing interface (FESEND) 
for eventual transmission to the terminal device. It also checks the 
operational status of destination terminals. Should it find a 
destination terminal not operational, it will redirect messages to an 
alternate terminal, if one has been named for that particular 
destination terminal. Otherwise, the Front End will intercept a 
message to a nonoperational terminal and queue it in the output queue 
assigned to that terminal to await its availability. 


752 PROCESSING 


An application subsystem may create four different types of 
output message text, identified by a value in the message header VMI 
field (MSGHVMI): 


e Preformatted (VMI=X'57') 


Text consists of both data and device control characters. 
All spacing and other formatting (titles, column headings, 
etc.) is included in the message text. Output processing 
consists merely of passing the message to the Front End via 
FESEND. If the destination terminal (MSGHTID) is the name of 
a broadcast group, rather than an individual terminal, a 
separate message is created for each terminal of the group. 
Except for broadcast terminal-ids, subsystems should use the 
service routine FESEND, which is more efficient than queuing 
via Output. 
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® Formatting Required, Variable Text (VMI=X’' 50) 


Text consists of a string of character data items to be 
inserted into a final message format defined by an Output 
Format Table (OFT) entry. Each data field is prefixed with 
an item code and length prefix, and an occurence factor (if a 
repetitive field), to identify the field. The OFT defines 
the position and content of titles, headings, etc., and 
defines the position where data fields from the message text 
are to be inserted. Output formats the final message, adding 
device-dependent control characters, and performs broadcast 
group processing, as described above. 


e Formatting Required, Multiple Segments (VMI=n 


This form is used when multiple messages are to be created 
for the same hardcopy terminal (such as a printer) and inter- 
leaving of other messages for the same device is not 
desired. The text is variable format as described above. 
The VMI code for the first (or header) segment is X‘'51‘'; for 
intermediate segments is X'52’ or X‘'5C’' depending on line 
types desired; and for the final seqment is X'53’. The final 
segment must be queued, even if no intermediate segments are 
created, in order that Output may release the terminal for 
other messages. See also the description of the DVASN 
service routine in Chapter 9. 


e Formatting Required, Fixed Text (VMI=X'72') 


Text consists of fixed length text fields in character or 
computational format. This type of message is routed to the 
Change/Display Utility, where it is converted to a Variable 


Text message and routed to the Output Utility. The fixed 
text is described to Change/Display by a Format Description 
Record (FDR). The first twelve bytes of the fixed format 


text identify the particular FDR which details the fixed 
fields of the message. Byte 9 within this header provides 
the segment type (see Figure 34). 


The application subsystem creates its output message (header and 
text) and directs the message to either the Output Utility or the 
Change/Display Utility by calling the service routine MSGCOL. The 
receiving subsystem codes and VMI in the message header specify the 
destination subsystem and message text formatting requirements. Figure 
34 summarizes message header specifications. In addition, the MSGHQPR 
field in the message header must be set to C’2’ if the originating 
subsystem might process segmented input. 


For complete details regarding the Output Utility and 
Change/Display Utility, refer to the Utilities Users Guide. 
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Variable Text Formatting 


Single Segment Messages: 


binary format for item 
code, length, (and 


occurrence number) 


Multi-Segment Messages: 


binary format 
first segment 


detail segment 

- repetitive items 
detail segment 

- non-repetitive items 
final segment 


Fixed Field Formatting: 


Single Segment Messages: 


Multi-Segment Messages: 


first seqment 
detail segment 

- repetitive items 
detail segment 

- non-repetitive items 
final segment 


Figure 34. 
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Message Header Specifications for the Output Utility 
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CONVERSATIONAL SUBSYSTEMS 


8.1 GENERAL CONCEPTS 


Conversational subsystems are defined as one or more subsystems 
designed to process more than one input message to complete a 
transaction. They effectively carry on a dialogue with the terminal 
operator, receiving an input message, retaining it and/or associated 
results of processing, issuing a response (perhaps a prompt for 
additional information), receiving another input message, retaining it, 
etc., until the transaction is complete. At the end of the 
conversation, appropriate files may be updated. 


8.1.1 Conversational Applications 


Typical applications which lend themselves to conversational 
processing are: 


e Operator prompting (multiscreen input) 
e Batch Data collection 


Prompting, or multiscreen input, applications typically consist 
of dialogues in which the terminal operator enters an input message, 
the information is analyzed by the application subsystem and the 
results of processing are saved; the application subsystem then sends 
an output message to the terminal, prompting the operator for the next 
piece of information required. This dialogue continues until the 
application subsystem has obtained all the necessary information to 
complete processing for the given transaction. 


Batch data collection may be conversational in that even though 
the input data is saved for later retrieval, the collecting application 
May need to return an error message requesting correction of invalid 
input data before saving the input record, or the application may need 
to request the input of a different type of record (for more detailed 
subsidiary information, intermediate totals, etc.). 


8.1.2 Conversational Transactions 


Conversational transactions involve the sending and receiving of 
more than one message in a terminal session. Each input message may be 
processed by related subsystems or by the same subsystem. A two-part 
conversational transaction is illustrated in Figure 35. 
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customer name > MESSAGE 


status request 


< account number RESPONSE 


current status 


sales order data p MESSAGE 
< verification of order RESPONSE 


Figure 35. Typical Conversational Transactions 


8.1.3 Retention of Information 


Assume a conversation in which three input messages and three 
responses are necessary to complete the transaction. A terminal, a 
subsystem and a storage medium on which to save the input messages 
and/or corresponding intermediate results of the processing are 
necessary components in the conversational environment. In the example 
illustrated in Figure 36, the subsystem receives information and 
prompts the terminal operator for additional information until it 
obtains all the required data. This intermediate information is also 
stored either in core or on a disk data set. After the final input 
message is received and processed, appropriate files are updated, 
intermediate data is deleted, and a final response is issued. 


Storage 


Input Message 1 
+ results 


Output Message 1<---Prompt for additional information 


Input Message 2---> Receive, access Input Message 1<--Input Message l 
Process + results 

Also store Input Message 2 > Input Message 2 
+ results 


Output Message 2<---Prompt for additional information 


Input Message 3---> Receive, analyze with prior <---- Input Message 
messages and results 1 & 2 + results 
Update files, delete prior data 


Output Message 3<---Final response 


Figure 36. Input Message Data Retention During a Conversation 
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8.2 IMPLEMENTING CONVERSATIONAL SUBSYSTEMS 


Conversational subsystems may be implemented in several ways, 
each characterized by the retention of initial and subsequent input 
and processing results. The method of retention differs, depending 
upon the method of implementation chosen. 


Control of the conversation, or the retention of the input 
messages and/or corresponding results of processing may be 
accomplished by using any one of the following methods of 
implementation: 


e The User SPA (User Extension to System Parameter List) 
@ The Store/Fetch Facility 

e The Dynamic Data Queuing Facility 

e The CONVERSE Service Routine 


In addition to the retention of the input environment, 
conversational subsystems have design considerations with respect to 
file updates and control of input verbs. These design considerations 
are discussed following a review of the four methods of retention of 
input messages and corresponding results of processing. 


Intercomm provides Front End conversational support to ensure 
that duplicate input is not processed. This is accomplished by 
defining applicable verbs and interactive terminals as conversational 
in the Front End tables. See the Operating Reference Manual. 
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8.3 SAVING INFORMATION IN USERSPA 


The user extension to the SPA is called USERSPA and is accessible 
to all Intercomm subsystems since the SPA is the second entry parameter 
to all subsystems. The SPA (Csect) is a 500-byte core-resident table. 
The user extention to the SPA begins at the 50lst byte and may include 
application-oriented areas, such as tables, counters, and switches for 
application subsystem use. Thus, the size of USERSPA is installation- 
dependent. The user portion of the SPA is optionally checkpointable 
and can be restored at system restart time. 


A portion of USERSPA may be divided into sections associating 
table space for each terminal, as illustrated by Figure 37. Each 
terminal-oriented area might be used for control data during 


conversational processing, until the conversation with that terminal 
completes. 


SPALIST macro 


COPYed 
member 
TABLE 
SPACE 
Table for TID2 USERSPA 


Figure 37. User and Terminal Table Space in the USERSPA 


The SPA is expanded by updating the Assembler Language member 
USERSPA on the system release library SYMREL. The updated version 
should be stored on SYMUSR. When assembling INTSPA, USERSPA is copied 
as the last entry in the SPA Csect. Therefore, any user additions would 
be referenced beginning with the 50lst byte. Any such additions should 
ordinarily be coordinated through the System Manager, as most 
application subsystems could be affected. 
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In the Dsect definition of SPA, as shown in Figure 38, three 
different applications have their own 50-byte areas defined:  (USERA, 
USERB, USERC) plus a table for their common use (COMTAB). The 
Assembler Language member USERSPA for this example would contain a 
definition of an area corresponding to SPAUSER. USERSPA could be 
defined as a systemwide COPY member for all Assembler Language 
routines. The Dsect is generated via the LINKAGE macro, or by coding 
the SPALIST macro, with no parameters. In the latter case, the macro 
must be preceded by a labeled DSECT statement which is the subject of a 
USING statement to establish addressability. 


SPALIST DSECT 
OPA... DC 


SPAUSER DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 


Figure 38. Sample USERSPA Declaration Within a Subsystem 


The following chart summarizes the advantages and disadvantages 
of the USERSPA method of implementation of conversational processing. 


Advantages Information saved in Core; no I/0 overhead. 
Accessed easily. 
Checkpointable and restorable at restart. 
Disadvantages The entire USERSPA is accessible to all Intercomm 
subsystems. Therefore a problem of control develops 
with respect to the possiblity of destruction of data 


by another subsystem, or security problems. 


Updating and maintenance of USERSPA may require 
reassembly of all subsytems which reference it. 


A potentially large area of storage must be allocated. 


Addressability, if area larger that 3595 bytes. 
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8.4 SAVING INFORMATION WITH STORE/FETCH 


Conversational information may be stored and later retrieved 
(either in storage or on a disk data set) by the Store/Fetch Facility. 
Information is retained via the STORE function, and retrieved via the 
FETCH function. The storage space may be released via the UNSTORE 
function. Saved information may also be updated. 


An operator prompting type of conversation involving one terminal 
and one or more application subsystem(s) could use Store/Fetch very 
efficiently for retaining information. Store/Fetch performs its 
function upon data strings. Data strings are logical entities of 
information (input messages to be retained or whatever other data the 
user intends to save), which are identified by unique user-defined 
keys. The information is accessible only to those subsystems which 
call a Store/Fetch service routine naming the data string by its unique 
key, which could include the current terminal-ID from the input message 


header. Therefore, there is more control over the information than 
there would be if it were to be saved in the USERSPA. The data strings 
are classified as either transient, semipermanent or permanent. The 


differences between these classifications are as follows: 


Disposition | Availability 


Transient 


Semipermanent Available across restart Disk 


Permanent Available across every system Disk 
start until explicitly unstored 


In conversational processing, permanent data strings should not 
be used. As to whether to use transient or semipermanent strings, the 
user must decide whether the information is critical enough to be 
preserved across system restart. If so, the data strings would be 
classified as semipermanent and would reside on disk. At restart time, 
the operator could then resume a conversation at the point of failure 
if subsystem logic can determine when the conversation was 
interrupted. If stored data is specified as transient, data is 
eligible to reside in core. Processing would thus be speeded up, as 
I/O overhead would be eliminated. At restart time, the operator would 
then start the conversation from the beginning. 


Detailed information on Store/Fetch, including the interface 
between application subsystems and the Store/Fetch service routines, 
may be found in Store/Fetch Facility. Application subsystem logic must 
determine whether the input message in progress is initial, 
intermediate or final. This determination is necessary to assure that 
the proper calls to Store/Fetch are issued when data is to be saved or 
retrieved. Once the determination is made, Store/Fetch may be used to 
manage the conversational information as shown in Figure 39. 
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Initial Input: 


STORE--create a new data string 
Intermediate Input: 
FETCH--retrieve existing data string 
STORE--update string: new information merged with existing data 


Final Input: 


FETCH--retrieve existing data string 


Process input and merge final information with existing data 


Update necessary files and create final output message 


UNSTORE--free data string storage 


Figure 39. Conversational Processing Using Store/Fetch 


Subsystem processing logic can be simplified by using one or more 
of the following techniques: 


e A ‘string-not-found’ return code from a FETCH request 
indicates intial input (no intermediate data stored). 


e A FETCH with the Delete option forces restart of the 
conversation from the beginning if the system fails, or the 
subsystem times out or program checks before the STORE of the 
intermediate data can be done. This technique also saves 
Store/Fetch and core storage resource overhead. 


e The STORE of the intermediate data should be done after the 
output message is processed. 


e File record(s) should not be updated until all intermediate 
data is collected. At this time the record(s) should be 
retrieved for update (exclusive control) and checked for 
external updates by unrelated processing since the 
conversation began. 


e Do not send the final confirmation output message until 
successfully updating the file(s). 
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8.5 SAVING INFORMATION ON A DYNAMIC DATA QUEUE 


The Dynamic Data Queuing Facility (DDQ) is a Special Feature 
available to Intercomm users. Detailed specifications on using DDQ may 
be found in Dynamic Data Queuing Facility. A DDQ provides the 
application subsystem with the ability to dynamically create, retrieve 
and delete logical data sets (or queues) of records on a BDAM data 
set. As illustrated in Figure 40, more calls are required to interface 
with the DDQ routines than are required to interface with Store/Fetch 
to obtain the same functions. However, a DDQ provides the ability to 
save several related data strings as a type of sequential file. The 
entire DDQ can then be processed by another subsystem or postponed for 
batch processing. A DDQ is most effectively used, not as a means for 
temporary storage of data during a conversation, but as a means for 
accumulating conversational results for subsequent processing, that is, 
for data collection. This facility can also be used for collecting 
data from related conversations with more than one terminal. 


The data queues may be either transient, single-retrieval 


transient, semipermanent or permanent. Single-retrieval transient 
queues cannot be read more than once. This type of DDQ, therefore, 
would not be suitable for conversational processing. The other queue 


types are distinguished by the following characteristics: 


ueue Type Characteristics 
YP 


Transient Must be passed to another subsystem or freed. 


Cannot be retrieved later. 


Not preserved across restart or normal startup. 


Semipermanent | Retrieved at a later point in time via a 
user-provided Queue Identifier (QID). 


Extra I/O overhead is involved in saving the queue. 
Can be freed by user requests. 


Queue must be completed (closed) in order to be 
preserved across restart. 


Existing semipermanent queues freed at normal startup. 
Permanent Same characteristics as semipermanent except that 
permanent queues are always preserved across any 
Intercomm start, warm or cold, if closed at least 
; once. 
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Figure 40 illustrates typical use of DDQ facilities in 
conversational processing. The application subsystem logic must 
determine whether input is initial, intermediate, or final. Final 
input, in this example, causes the queue to be closed and passed to 
another subsystem for asynchronous or postponed file updating. Thus, 
the terminal operator, upon receipt of the final output message, can 
begin another conversation without waiting for file updates to occur. 
This technique is particularly useful for files which do not require 
up-to-date inquiry response such as order entry, personnel, etc. 


Initial Input: 


QBUILD -- Create a new queue 
QWRITE -- Save input message and related data 
QCLOSE -- Save the DDQ 
Intermediate Input: 
QOPEN Open the queue 


QREADX -- Read the record or QWRITE to add 
with intent to update to the queue 


QWRITEX -- Update the record 
Save the DDQ 


Final Input: 


QOPEN Open the queue 


QREADX -- Retrieve the record | or QWRITE to add 
to the queue 


QWRITEX -- Update the record 


QCLOSE -- Pass the DDQ to another subsystem which will update 
files and free the queue. 


Issue final output message. 


Figure 40. Conversational Processing Using Dynamic Data Queuing 
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8.6 SAVING INFORMATION VIA THE CONVERSE SERVICE ROUTINE 


The final method of retaining information for a conversation is 
to use the Intercomm system service routine CONVERSE. The CONVERSE 
routine is called by an application subsystem when input from a 


terminal is required to continue processing a _ transaction. The 
application subsystem stops processing until the next input message is 
received. Control is returned to the next sequential instruction 


following the call to CONVERSE. 


Application subsystems are designed more easily with CONVERSE, as 
it is simpler to control the sequential order of the messages. 
However, the use of CONVERSE is not encouraged, as it ties up Intercomm 
resources. Dynamic storage associated with the initial and subsequent 
input messages is retained during the call to CONVERSE. Storage 
requirements for subsystems would be greater than when other 
conversational techniques are used, because one subsystem contains 
logic for all message types of a conversational transaction. It is far 
more efficient to design conversational subsystems which retain control 
only for the amount of time necessary to process one message than to 
tie up system resources while each input message in the conversation is 
in turn received, kept, analyzed and responded to in one execution of 
one application subsystem. When CONVERSE is used, dynamically loaded 
subsystems remain in storage until all "conversations in progress" have 


terminated. Intercomm restart processing of such subsystems restarts 
the conversation from the beginning. All intermediate messages are 
discarded. 


The saving of information in the USERSPA or in a Store/Fetch data 
set or in a DDQ does not require an application subsystem to contain 
logic for time-outs. The use of CONVERSE does. If the next input 
message is not received in the time limit specified by the user, a 
time-out occurs, which must be handled by subsystem logic. 


The CONVERSE program keeps track of conversational requests by 
terminal and subsystem, and separates messages accordingly. Hence, any 
subsystem may be in conversation with any number of terminals 
simultaneously. 


An example of the use of CONVERSE in a two-part conversation is 
illustrated in Figure 41. 
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SUBSYSTEM 
CALLED BY 
MONITOR 


Part A Logic PROCESS 


INPUT Beginning of Conversation 
MESSAGE A 


FORMAT 


OUTPUT Pass Message to Front End 
MESSAGE A 


| CONVERSE | 
SAVE THE CONVERSE saves terminal 
INTERCOMM identification, subsystem code, 
ENVIRONMENT storage pointers, etc. 


When the next message with the 
Part B Logic PROCESS same terminal-id arrives, the 
REPLY subsystem resumes from this point 
MESSAGE B referencing the original areas 
and the new message. 


FORMAT 


OUTPUT Pass message to Front End 
MESSAGE B 


RETURN TO 
MONITOR 


Figure 41. Conversational Subsystem Logic Using Converse 
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8.6.1 Subsystem Design Using CONVERSE 


The Intercomm system service routine CONVERSE is called when 
awaiting additional input in response to some prompting message. Since 
any interval may elapse before the next message is received, CONVERSE 
will save information in its own control table for each conversation 
and return to the Subsystem Controller while waiting for the response. 


The call to CONVERSE specifies a time limit within which a reply 
message should be received. If it is not received during the specified 
interval, then the subsystem is entered at the next instruction 
following the call to CONVERSE and its message parameter is adjusted to 
point to a time-out message supplied by CONVERSE. That message (header 
plus text) could then be switched to the Output Utility. The terminal 
identification in the header is that of the non-responding terminal. 


Coding format: 


There are two coding formats available to reentrant Assembler 
Language subsystems for calling the CONVERSE subroutine: as _ core 
resident or in an overlay area. 


The coding format, if CONVERSE is always resident, is as follows: 
[symbol] CALL CONVERSE, (parm,time) ,VL,MF=(E, list) 

If CONVERSE may be in a transient overlay area: 
[symbol] CALLOVLY CONVERSE, (parm,time) ,VL,MF=(E, list) 


where: 


e parm is the address of the parameter list passed to the 
subsystem at its entry point. The contents of the parm 
register is specified on the LINKAGE macro. If the input 
message is not freed by the subsystem (or a call to MAPIN) 
CONVERSE will free it. If freed by the subsystem, zero the 
first word of the input parameter list. If the input message 
is edited by a call to EDITCTRL, set the address of the 
edited message into the first word of the input parameter 
list. 


® time is the label of a fullword binary value indicating an 
interval limit (in seconds) within which a subsequent message 
is expected. A zero value for the time limit will bypass the 
automatic time-out feature. 


When processing resumes following the call to CONVERSE, the 
environment appears as it was before the call--except the input message 
parameter (unless there was a time-out) now points to the most recent 
message from the terminal. It is the subsystem’s responsibility to 
verify that the message received following the call to CONVERSE is 
actually the appropriate message expected in the logical sequence of 
the conversation. 
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In calling CONVERSE from an Assembler Language subsystem, the 
address of the parameter list for the previous message being processed 
by the subsystem must be passed. Upon return, the address of a new 
parameter list (with the address of the new message) must be loaded to 
the appropriate register. This coding sequence is illustrated below: 


LINKAGE MSG=(R8) , PARM=(R/) ,SPA=(R9)... 


MSGCOL, (. Bek tee “an ved 

CONVERSE, ((R7) , TIME) , VL,MF=(E, list) 
R7,list 

R8 , PARMMSG 


Q output message 


If the new message from the terminal requires editing, CONVERSE 
will call the Edit Utility before passing the new input message address 
to the subsystem. If editing is unsuccessful, error messages are sent 
back to the terminal (see Figure 42). 


Figure 42 shows the CONVERSE return codes and the contents of 
message text for a time-out condition. These return codes are fullword 
binary values in register 15 indicating the condition for return. 


Return Codes 


0 (X'00') 


reflects the address of the new input message. The 
message will have been edited successfully if the 
Front End Verb Table shows editing required. (If 
editing is unsuccessful, error messages will be sent 
to the terminal, and the subsystem is not reactivated 
until either a subsequent input message is edited 
successfully or an automatic time-out occurs.) 


CAUTION: The CONVERSE automatic time-out is not 
extended if a message is found in error by 
the Edit Utility. 

17 =(X¥'11') No core available for CONVERSE control blocks; 

conversational mode not initiated. 

18 (X'12') Time-out expired. The entry parameter input-message 
reflects the address of an error message generated by 
CONVERSE. The message header contains the appropriate 
terminal identification. The message text is: 


*PMI*CONVERSE*ANTICIPATED MESSAGE NOT RECEIVED 
WITHIN USER SPECIFIED TIME INTERVAL 


Figure 42. CONVERSE Return Codes 
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Control of the conversational program environment is accomplished 
by Intercomm in different ways, depending on the subsystem’s residency: 


e Resident 


The dynamic work space for one message is retained pending 
arrival of the next message from the terminal; the subsystem 
will continue to process messages from other terminals. 


e Overlay Loaded 


Same as above, except the loaded overlay region may contain 
other subsystems to process other messages during (and after) 
"CONVERSE time." 


@ Dynamically Loaded 


Same as above, except the subsystem remains in core until all 
"conversations in progress" have terminated. 


Conversational subsystem logic must be designed with care 
regarding file access. Selected files should be released prior to the 
call to CONVERSE. If not, other subsystems accessing the same files or 
other messages in process in the same subsystem may "time out." This 
may occur because an operating system control block is associated with 
the access to the file and is not "freed" until the file is released. 
If a file is accessed prior to the call to CONVERSE and released after 
the call to CONVERSE a "lock out" situation may occur. 


Assembler Language subroutines may not call CONVERSE. 
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8.7 DESIGN CONSIDERATIONS IN CONVERSATIONAL PROCESSING 


In order to ensure file integrity, conversational subsystems 
performing file and/or data base updates should be designed to perform 
the updates for the last message in the conversation. Alternatively, 
control may be passed (via message queuing) to a non-conversational 
subsystem to perform the updates. 


8.7.1 Control of the Input to Conversations 


Conversational subsystems expect ordered input. They must be 
designed to analyze input messages and to determine which message in 
the sequence has been received. Control of the input may be exercised 


by the terminal operator or by the application subsystem(s). 


The terminal operator may be given a specific sequential list of 
messages to input at the terminal for a given verb or verbs. This 
method would probably be used for data collection applications, in 
which more messages are sent to the application subsystem than are 
received at the terminal. It could also be used for any conversational 
application in which the order of input is fixed. 


The application subsystem may control the input sequence by 
analyzing an input message, processing it, and issuing a response 
informing the operator about the content or format of the next input 
message. The response may direct the operator to input another verb 
(that of a related subsystem). Subsystem-controlled input is good for 
conversations in which the "next" desired piece of information may vary 
depending upon the contents of a file record, or a table, or the 
setting of a switch in an area saved between subsystem activations. 


8.7.2 Assigning a Verb to a Terminal 


To eliminate the requirement for an operator to key in a verb 
with each input message, the operator may enter a system control 
command message to LOCK a specific terminal to a particular verb. The 
Front End then prefixes that verb to each input message from that 
terminal. The operator may enter another control message, UNLK, to 
unlock the terminal from the verb. See System Control Commands. 


The LOCK/UNLK commands processed by the Front End can also be 
issued by a _subsysten. When a LOCK is in effect, all subsequent 
messages from the specified terminal will be automatically prefixed by 
the verb specified in the LOCK command. This LOCK remains in effect 
until UNLK is issued. With LOCK in effect, some advantages are: 


e The terminal operator does not have to keep reentering the 
same verb. 


e A new verb cannot be entered during the conversation. 
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Either the subsystem or the operator may control the input 
sequence by locking and unlocking the terminal to different verbs at 
different points in, or at the end of, the conversation. 


Optionally, the Intercomm AUTOLOK feature may be defined for the 
verb in the Front End Verb Table, which dictates that when that verb is 
input from the terminal, the terminal is to be automatically locked to 
that verb. Subsequently, the terminal is to remain locked until 
specifically UNLKed by the operator or processing subsystem. 


The format for the LOCK/UNLK commands (message text) is as 
follows: 


LOCKSTPUxxxxx$vvvv@ 
UNLKSTPUxxxxx@ 
where: 
XXXXX 
is the five-character terminal identification 
VVVV 
is the four-character verb 
@ 
is the end-of-transmission character (X‘'26') 
$ 


is the system separator character as defined for the 
installation. 


The preformatted message constructed by a subsystem must be 
prefixed with the standard message header for FESEND 


(MSGHRSCH=X'00' ,MSGHRSC=X’00' , VMI=X’57"). This message is passed to 
the Front End via FESEND (see Chapter 9) and the LOCK or UNLK takes 
place. No response message is sent to the terminal when such 


processing is requested by a subsystem. 
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USING INTERCOMM SERVICE ROUTINES AND FACILITIES 


9.1 SERVICE ROUTINES AND FACILITIES 


This chapter further describes use of Intercomm service routines 
and facilities available to Assembler Language subsystems. These are 
as follows: 


Pass message to another subsystem (MSGCOL) 

Message Logging (LOGPUT) 

Pass Message to Front End (FESEND) 

Front End Control Messages (FECMs) 

Perform Binary Table Search (BINSRCH, BINSRCH2, BINSRCH3) 
Data Field Search Routines (PMIFINDB, PMIDLTDB) 

Segmented Message Routines (GETSEG, DVASN) 

Dispatcher Related Routines (IJKPRINT, IJKTRACE, IJKDELAY) 
In-core Table Sort (INTSORT) 

Other Intercomm Service Facilities 


Loading Service Routine Entry Points from the SPA 
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9.2 MESSAGE SWITCHING (MSGCOL) | ) 


Message Collection is a system service routine. It is 
responsible for queuing messages destined for processing by another 
subsystem, that is, message switching. MSGCOL controls the queuing of 
messages via the message header fields MSGHRSCH and MSGHRSC, the 
receiving subsystem code. 


The logic of an application subsystem might be such that the 
input message is modified within its dynamic area to become an output 
message to switch to another subsystem. To do this, the length of the 
input message must not be altered (data may not be added). Queuing the 
message for the next subsystem is then done by calling Message 
Collection (MSGCOL); Message Collection then owns and is responsible 
for the management of the message area. In this case, the subsystem is 
not responsible for freeing the input message area. 


Coding format: 
[symbol] CALL MSGCOL, (message,SPA) ,VL,MF=(E, list) 
where: 
message is the address of the (input) message to be queued 
SPA is the address of the System Parameter Area. 


MSGCOL return codes indicate the result of the queuing. The # 
return code is a fullword binary value in Register 15. (See Figure 


43.) Regardless of the result, the calling program no longer has any 
control over the area of dynamic storage occupied by the message. 


Se SS ee ee ES a LE 


Return Code 


NE a A ge ee eS eS TS NEE ee Te ee A ee ETS eee erence es Te ee ee ee 


Meaning 


Ae ape me caper ie nen ms AT a aan Renan aR na a es nna ae en eager Lee ee a et ee ES 


Message queued successfully 


No room on queue (entry made on system log) 
or message rejected for delayed subsystem 


Invalid subsystem code (entry made on system log) 


Figure 43. Message Collection Return Codes 


Recovery action for umsuccessful queuing might be to return to the 
System Monitor with a return code of 8 or 12. A message would then be 
sent to the terminal that originated the input message being processed, 
if USRCANC (PMICANC) is included in the Intercomm linkedit. S 
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9.3 USER LOG ENTRIES (LOGPUT 


An application subsystem may require entries on the system log 
for many different situations: 


e Application-dependent security violation or other 
application-dependent error recording. 


e Log entries rather than snaps used to trace the progress of a 
message while testing. 


e Any application-oriented requirement for a record on the 
system log. 


e Before- and/or after-image records of file updates (if not 
using the Intercomm File Recovery special feature). 


User log entries are identified by unique codes in the message 
header log code field (MSGHLOG) and hence can be recognized by any 
batch program processing the log off-line. Messages to be logged 
consist of a standard 42-byte header and message text. The log code 
field in the message header may have any value from X'41' to X'6F’. 
Logging is performed by calling the Intercomm system service routine 
LOGPUT. The date and time stamp in the message header (MSGHDAT and 
MSGHTIM) will be updated by LOGPUT prior to writing to the log. Log 
entries may subsequently be suppressed for later Intercomm executions 
by modifying the LOGTROUT translate table in the LOGPUT routine. Any 


message having a log code in the header which translates to X'FF’ will 
not be logged. 


The length of the record on the log is controlled by the value of 
MSGHLEN in the message header and must be at least 42. LOGPUT will not 
write out messages longer than the logical record size of the log (see 
INTERLOG JCL description in the Operating Reference Manual). 


Coding format: 
[symbol] CALL LOGPUT, (message) , VL,MF=(E, list) 
where: 


message is the label (address) of the message (header plus text) 
to be logged. 


There is no return code from LOGPUT. 
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9.4 PASS MESSAGE TO FRONT END (FESEND, FESENDC) 


FESEND (or FESENDC) is called to pass a message to the Intercomm 
Front End for transmission to a terminal. The entry point FESENDC of 
FESEND copies the message to a new area of storage, and then proceeds 
with FESEND logic. The message header field MSGHTID specifies the 
destination terminal or broadcast group name. FESEND then requests 
queuing of the message on the associated terminal queue. If a 
broadcast group is specified, FESEND creates an individual message for 
each terminal of the group and requests queuing for each of those 
messages. All terminals in the broadcast group must be of the same 
type, as defined in the Back End Station and Device tables (see Chapter 
ip 


FESEND accepts two types of messages: preformatted (VMI=X'57') 
message text, which contains the control characters and data for 
transmission to the terminal except for start-of-text sequence(s) to be 
added by the Front End; and fully-formatted (VMI=X'67') message text, 
which contains all control characters and data ready for transmission 
to the terminal. (MMU produces fully-formatted messages. ) If 
segmented input messages may be processed, set MSGHQPR to C'2' before 
calling FESEND. If passing the message to the Front End is for any 
reason unsuccessful, the subsystem is notified by a return code in 
Register 15, and recovery action may be taken. 


FESEND tests whether messages sent to the Front End might be 
system commands or for control purposes. Such messages control Front 
End operation and generally cause no output to a terminal. Front End 
Control Messages (FECMs) are described later in this chapter. All 
system control commands and message text contents are documented in 
system Control Commands. 


FESEND becomes the owner of the area of storage occupied by the 
message. Do not attempt to free this area or reference it once FESEND 
is called. FESENDC copies the message to a new area, the original area 
still belongs to the caller (and may be in the dynamic save/work area 
and ultimately freed via RINLINK, rather than an acquired area which 
requires freeing by STORFREE before the RTNLINK). 


Coding format: 


[symbol] CALL {FESEND }, (msg-addr[,ret-code[,option-codes]]), 
{ FESENDC} 
VL,MF=(E, list) 


where: 
msg-addr points to the first byte of the message (header and 
text) to be passed (copied) to the terminal queue. 


return-code optionally points to a two-byte character field 


where FESEND will place a return code indicating whether or 
not processing was successfully completed (see Figure 44). 
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option-codes optionally points to a four-byte character field 
containing Front End processing codes as follows: 


Byte 1: CRT Release option code: 
blank or X’‘00'--do not release (prevent screen 
overlay) next message (default) 
C’R’--release (allow overlay) next message to CRT 
C’C’--release next message, but do not cancel 
Front End conversational time-out 


Byte 2: VTAM Response option code (overrides Front End 
Network Table definition for terminal): 
blank or X‘'00'--no override (default) 
C'O’--Dl response 
C’'E’--El response 
C'F’--D2 response 
C'G’--E2 response 


Bytes 3 and 4: Not used (set to blanks or binary zeros) 


FESEND also returns codes in hex in register 15; the codes and possible 
recovery actions are listed in Figure 44. A nonzero return code means 
the message was not queued for the Front End. Return codes 16-24 
should only occur during subsystem testing. Regardless of the result, 
the calling program no longer has any control over the area of dynamic 
storage occupied by the message if FESEND was called. 


= —" 


Return Code 


Low-core condition encountered; attempt a retry 
by invoking FESEND again or return to Intercomm. 
(See Figure 14.) 


I/O error (see Figure 14) encountered on disk 
queue; return to Intercomm. 


Invalid terminal-ID; no recovery action required. 
Check with System Manager to verify terminal/ 


Invalid message header; return to Intercomm. 
See also error message MG602I and Snap 51. 


Figure 44. FESEND Return Codes 
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9.5 FRONT _END CONTROL MESSAGES } 


The Front End Control Message (FECM) facility provides three types of 
Front End control messages which may be used by application subsystems 
for: 


® Front End data queuing (FECMDDQ) 
e Front End feedback messages (FECMFDBK) 
@ Front End queue release (FECMRLSE) 


A FECM is generated by an application program call to a service 
routine. The generated feedback message text is complete. The header 
field MSGHLEN has been set; bytes 3-42 are not modified. If the user 
has copied a valid header to the FECM message area prior to the call, 
only the sending subsystem codes (SSCH,SSC) and the VMI must be set 
(X'57'). The generated FECM must then be passed to the Front End by a 
call to FESEND in the application program. 


After a call to any Front End Control Message facility, a return 
code is placed in the first byte of the status word and the binary 
value of the return code is returned in register 15: 


No storage available to build FECM 


Figure 45. FECM Return Codes 


9.5.1 Front End Data Queuing 


Front End data queuing (FECMDDQ) works in conjunction with the 
Dynamic Data Queuing Facility. It provides the user with a more 
efficient way of handling groups of related output messages. An 
application may pass a Dynamic Data Queue (DDQ) to the Front End via a 
FECM. The DDQ contains messages to be sent to a terminal. This is a 
more efficient design approach than sending one message at a time to 
the Front End via FESEND, and prevents interleaving of unsolicited 
messages with those on the DDQ. This feature is particularly useful 
for printed reports. The messages on the DDQ must be preformatted 
(VMI=X'57') or fully formatted (VMI=X'67'). The Dynamic Data Queuing 
Facility manual contains detailed information on DDQ concepts, 
facilities and implementation, and specific design considerations for 
Front End Data Queuing. MMU uses this facility (FECMDDQ), when 
requested for multipage printer output. 
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Coding format: 


[symbol] CALL FECMDDQ, (status-word, fecm-area,ddq-id[,ddq-disp]), 
VL,MF=(E, list) 


where: 
status-word is a fullword (aligned) required by the facility. 


fecm-area is a 112-byte area to contain the FECM (header and 
text). The user should initialize the header prior to the call, 
probably by copying the input message header to this area. If 
this parameter is zero, the facility will acquire the area of 
storage for the caller. (Register 15 has a value of 8 on the 
return from the call if storage was not acquired.) The caller 
must then complete the message header area of the FECM. Only 
MSGHLEN is set by the facility. 


ddq-id is the sixteen (16) byte DDQ identifier. 


ddq-disp is a one-byte code indicating DDQ disposition after all 
messages are transmitted: 


C'S’ means SAVE the DDQ (required if MSGHTID is a broadcast 
group name) 


C'F’ means FREE the DDQ (default) 


NOTE: The ddq-disp parameter may be omitted if the DDQ is to be freed 
after all the messages are transmitted (default). All the above 
parameters must be in dynamic storage if the calling program is 
loaded above the l6meg line under MVS/XA or ESA. 


9.5.2 Front End Feedback Messages 


This type of FECM (FECMFDBK) is used by an application to 
determine that all prior messages queued for a terminal (before the 
FECM) have been transmitted. In this way, an application subsystem can 
be notified that certain critical messages have indeed been 
successfully transmitted. 
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Subsystem logic creates all normal output messages and passes 
them to the Front End (via FESEND, MMU, or by queuing messages for 
Output). Generation of a feedback message is then requested by a call 
to a FECM service routine. The feedback message is then processed in 
the same way as the other messages for the terminal (queued via FESEND 
or the Output Utility). When the Front End retrieves the feedback 
message, it is routed to the subsystem specified when the feedback 
message was generated rather than to the destination terminal. 


Feedback messages may also be used in conjunction with Front End 
Data Queuing. A feedback message could be an intermediate, or the 
last, message on a DDQ passed to the Front End. If the DDQ was created 
via MMU (a MAPEND call option), then the feedback FECM must be created 
and queued by the subsystem on return from the MAPEND call. 


Coding format: 


[symbol] CALL FECMFDBK, (status-word, fecm-area,fecm-rsc, 
fecm-text) ,VL,MF=(E, list) 


where: 
status-word is a fullword (aligned) required by the facility. 


fecm-area is a 78-byte area to contain the FECM (header and 
text). The user should initialize the header area prior to the 
CALL, probably by copying the input message header to this area. 
If this parameter is zero, the facility will acquire the area of 
storage for the caller. (Register 15 has a value of 8 on the 
return from the call if storage was not acquired.) The caller 
must then complete the message header area of the FECM, only 
MSGHLEN is set by the facility. 


fecm-rsc is a two-byte receiving subsystem code (high/low) to 
specify the feedback message destination subsystem. 


fecm-text is a 16-byte area containing the desired feedback 
message text. 


The generated feedback message text is complete. The header 
field MSGHLEN has been set; bytes 3-42 are not modified by FECMFDBK. 
If the user has copied and set a valid header prior to the call, no 
further modification to the header is required. 
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9.5.3 Front End Queue Release 


This type of FECM (FECMRLSE) allows the subsystem to override the 
normal Front End Logic for CRTs, which requires a one-for-one 
correspondence between input and output messages. When the release 
FECM is processed by the Front End, it causes a subsequent response 
message queued for the terminal identified by MSGHTID in the FECMRLSE 
message header to be transmitted immediately, rather than waiting for 
input (RLSE command) from the terminal operator. Because of protocol 
restrictions (HDFF) on VTAM Front End IBM SDLC 3270 CRT processing, the 
CRT release option for the first call to FESEND should be used (see 
Section 9.4) as a release; because if the terminal is already in send 
mode, it is necessary to turn the line around before sending the 
released message, which may confuse the terminal operator. 


A release FECM might be used if a subsystem queues more than one 
output message to the CRT terminal due to a considerable amount of 
processing (file/data base I/0) being necessary between messages. The 
first message might be an immediate response to the terminal operator 
indicating the input request is being processed, while the second 
message is the ultimate result of the requested processing. A release 
FECM could also be used to force immediate transmission of a critical 
message to another CRT (other than the input terminal). Such 
processing should be used with caution because unsolicited messages can 
cause confusion for the terminal operator and may clear an existing 
screen format or displayed message. 


Coding format: 
[symbol] CALL FECMRLSE, (status-word, fecm-area) ,VL,MF=(E, list) 
where: 


Status-word is a fullword (aligned) area required by the 


facility. 

fecm-area is the label of a 60-byte area to contain the generated 
FECM (header and text). The user should initialize the header 
area prior to the call, probably by copying the input message 
header to this area. If this parameter is zero, the facility 
will acquire the area of storage for the caller. (Register 15 


has a value of 8 on the return from the call if storage was not 
acquired.) The caller must then complete the message header area 
of the FECM, only MSGHLEN is set by the facility. 
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9.6 PERFORM BINARY TABLE SEARCH (BINSRCH _BINSRCH2 , BINSRCH3 ) 


The module BINSRCH is automatically included as a resident 
Monitor module. This module performs two functions: it will search a 
sorted table for an entry equal to a passed argument, using a binary 
search technique--the entry point to perform this function is BINSRCH2; 
and it will search an index table whose first halfword or fullword of 
each entry is an offset/2 from the base of the actual table to be 
searched (points to an individual table entry). The sequence of index 
table entries reflects the ascending sequence of values (keys) in the 
actual table (which is not sorted). The entry points to perform this 
function are BINSRCH (if the first halfword of the index entry contains 
an offset to the corresponding entry in the actual table) or BINSRCH3 
(if the first fullword of the index contains the offset). 


Coding format: 
[symbol] CALL {BINSRCH }, (arg,#entries,entry-len,table,offset,arg-len, 
{ BINSRCH2 } 


{ BINSRCH3} 
index[ ,shift]),VL,MF=(E, list) 


where: 
arg is the address of the search argument. 


#entries is a fullword containing the total number of entries in 
the table (BINSRCH2) or index (BINSRCH and BINSRCH3). 


entry-len is a fullword containing the length of a table entry 
(BINSRCH2) or of an index entry (BINSRCH and BINSRCH3). 


table is the base address of the table to be searched. 


offset is a fullword containing the offset within an actual table 
entry at which a comparison is to be done. 


arg-len is a fullword containing the length of the _ search 
argument. 


index is the address of the first index entry (BINSRCH or 
BINSRCH3) or zeroes (BINSRCH2). 


shift is a fullword containing the shift amount to shift the 
offset in an index entry to displace to the beginning of the 
associated table entry. This parameter is optional, and if 
absent, a shift value of 1 is assumed. The displacement 


calculated will be equal to Index-Offset*2*Shift. (BINSRCH and 
BINSRCH3 only.) 
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| BINSRCH, BINSRCH2 or BINSRCH3 will return the following to the 
calling program: 


e Register 15: the address of the matching table entry 
(BINSRCH2), or the address of the matching index entry 
(BINSRCH or BINSRCH3), or, if not found, the first table (or 
index) entry whose key exceeds the search key. 


@e Register 1: the address of the actual matching table entry, 
or zeros if none found. 


9.7 DATA FIELD SEARCH ROUTINES (PMIFINDB,PMIDLTDB) 


When using the Edit, Output or Change/Display Utilities, the 
search routines allow the user to add, delete, or locate a variable 
format data field in an area (message text). These routines are entry 
points in the system module PMISERC3. The variable format data field 
must always be formatted as follows: 


Byte 1: Item Code (in binary), identifying the data. 


Byte 2: Length (in binary), containing the number of bytes 
which follow. This length does not include the item 
code or the length byte itself. 


a Byte 3: Beginning of the data text, or if an occurrence 
number (line number) for the item code exists, it is 
contained in the 3rd byte (in binary) and the data 

will follow starting in the 4th byte. 


The area containing the variable format data fields will be referred to 
as the text area in the following discussion. 


Specifically, the search routines are used to find the address of 
an item code, (or an item code and occurrence number), or to update a 
text area by adding or deleting a data field. The search routines are: 


PMIFINDB - Finds the address of a data field with a given item 
code (by line number or by occurence number) in a 
text area. 


PMIDLTDB - Adds or deletes a data field with a given item code 


(by line number or occurence number) within a text 
area. 
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9.7.1 PMIFINDB - Find a Data Field 
The purpose of this routine is to find a data field with a given 
item code (optionally by occurrence or line number) within a text 
area. Search by occurrence number will locate a data field with a 


specific occurrence number, or with a specific line number if the data 
fields in a message area occur vertically rather than horizontally. 


Coding Format: 


[symbol] CALL PMIFINDB, (start-address,SPA,end-address,codes,0Q), 
VL,MF=(E, list) 


where: 
start-address is the beginning location address for the search 
SPA is the address of the System Parameter Area 


end-address is the ending location address for the search (end of 
text area) 


codes is the address of a 3-byte field containing 


byte 1: item code (binary) 


byte 2: occurrence/line number (binary) - X'‘'00’if no 
occurrence/line search is required 


byte 3: character action code-- 
1: search by occurrence/line number 
2: search by sequence (obsolete) 
3: next occurrence following specified 
occurrence number (obsolete) 


Q saves space in the parameter list for the address of the found 
variable length data field (starting with the requested item 
code). 


If the search is successful, the address of the found data field 
will be returned in the 5th parameter. If the search is unsuccessful, 
one of the following conditions occurs: 


® If the item code could not be found, binary zeros will be 
returned in the 5th parameter field, return code in register 
15 is 0. 


e If the location addresses are invalid (end lower than begin) 
or the action code is invalid (other than 1), a return code 
of 1 (in register 15) will be returned to the calling module, 
and the 5th parameter field will be zeroed. 
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9.7.2 PMIDLIDB - Delete or Add a Data Field 
The purpose of this routine is to delete or add a variable length 
data field with a given Item Code (optionally by occurrence number) 
within a particular text area. An added field is moved to the end of 
the used (non-zero) text area and the next byte is set to X'00’. Fora 


deleted field, the remaining text area is shifted left over the deleted 
field, and the trailing unused portion is set to binary zeroes. 


Coding format: 


[symbol] CALL PMIDLTDB, (start-address,SPA,end-address,field,action), 
VL,MF=(E, list) 


where: 
start-address is the beginning location address for the search 
SPA is the address of the System Parameter Area 


end-address is the ending location address for the search (end of 
text area) 


field is the address of a field as follows: 


For Delete Action - Two-byte field containing: 
a) Item Code (in binary) 
b) Occurrence Number (in binary) 
(if no occurrence number is necessary, this byte 
must contain X’00') 


For Add Action - Variable length data field containing: 


a) Item Code 1 byte 
b) Length of c below 1 byte 
c) Occurrence Number (optional) 1 byte 

and Data x bytes 


action is the address of 1l-byte action code field containing: 
C'l’ for add action, or 
C'2' for delete action. 

If an add or delete action took place, a return code of 0 will be 
passed to the subsystem in register 15. If the operation was not 
successful, one of the following return codes will be passed in 
register 15: 

l--invalid action code or location addresses 


2--no match on Item Code for delete action 


3--no room to add variable length data field. 
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9.8 SEGMENTED MESSAGE INPUT (GETSEG) 


In designing the message processing logic for an application 
subsystem, the possibility of receiving a multisegmented message for 
processing must be considered. This type of input message requires a 
special Intercomm service routine module GETSEG. When an application 
subsystem receives the first segment of a multisegmented message, 
identified by a value of 0 (X'FO') in the message header MSGHQPR field, 
it must call the GETSEG subroutine in order to receive the remaining 
segments of the message. GETSEG must be called for each message segment 
(intermediate segment MSGHQPR=1), until the final segment is obtained 
(MSGHQPR=3). 


Coding format: 
[symbol] CALL GETSEG, (msgarea,ret-code,sctaddr) ,VL,MF=(E, list) 


where: 


msgarea is the name (address) of an area, defined within an area 
acquired by a STORAGE macro or in the dynamic save/work area, in 
which to place the next message segment 


ret-code is the address of a one-byte area into which GETSEG 
passes a return code 


sctaddr is the address of the area passed upon entry to the 
subsystem which defines the Subsystem Control Table (SCT) entry for the 
application program. 


As a result of this call, GETSEG will obtain the next message 
segment and will call the Edit Utility (if the message requires 
editing) before passing it to the subsystem for processing. If the 
incoming message goes through the Edit Utility, care should be used in 
selecting parameters used by the Edit Utility; they must appear in 
identical form in every segment of the message. The return code passed 
to the application subsystem by GETSEG in the specified area, is in 
character format. The possible return codes are listed below: 


Meaning 


Message is present. 


There is a message present, but core is not 
available. The subsystem should return to the 
| Subsystem Controller with an identical return code. 


Message is present, but Edit Utility could not 
process it. 


Figure 46. GETSEG Return Codes 
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9.8.1 Segmented Message Output Terminal Assignment (DVASN) 


The DVASN message processing service routine is used in 
conjunction with the Output Utility. DVASN is called by a subsystem to 
obtain exclusive use of a terminal for the purpose of transmitting a 
multisegment message without interruption, that is, without interleaving 
of messages (such as printer report pages queued by other subsystems). 
The DVASN subroutine (module name PMIDVASN) must be called before 
queuing (via MSGCOL) the first segment of a multisegment message for 
formatting by Output. 


Coding format: 
[symbol] CALL DVASN, (cmp,SPA,term,oft,ret),VL,MF=(E, list) 


where: 


cmp is the address of a halfword field containing the number of 
the company or division being serviced (obsolete - use binary 
zeros for the number). 


SPA is the address of the System Parameter Area. 


term is the address of a field containing the destination terminal 
(broadcast group) name, or of the field MSGHTID in the message 
header. 


oft is the address of a halfword field containing the OFT number 
of the format about to be started. 


ret is the address of a five-byte field in which will be returned 
the assigned terminal-ID (alternate tid-name if original down in 
Back End Station Table), or binary zeros if not found. 


As a result of this call, DVASN will assign the terminal to the 
subsystem and designate it in a "multi-segmented-message- 
transmission-in-progress" condition in its respective entry in the Back 
End Station Table (see Chapter 2). This action thus prevents other 
messages from being transmitted to the designated terminal until its 
busy status is subsequently freed by the Output Utility (only in Control 
Region in a Multiregion environment). 
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9.9 DISPATCHER RELATED ROUTINES 


Three Intercomm service routines are available to an application 
subsystem during execution. They are Dispatcher-related in that they 
were developed for internal use, but are also applicable within message 
processing logic. 


e IJKPRINT formats a print line for SYSPRINT and includes page 
overflow logic. 


@ IJKTRACE provides a list of Dispatcher task queues for 
purposes of debugging. IJKTRACE utilizes IJKPRINT. 


e IJKDELAY provides a simple means of coding a time delay (for 
multi-threading) of approximately 100 milliseconds within an 
application subsysten. 


9.9.1 JIJKPRINT - Direct Output Line to SYSPRINT 


This subroutine calls the PUT entry point in the File Handler to 
output a print line image of IBM standard format V (variable-length) 
records, with an ASA printer spacing control character as the first 
text byte. (Maximum logical record length is 137.) A count is 
maintained of the number of lines printed on the text page; when the 
count exceeds a pre-assembled value, the next line output will specify 
a skip to head of form (ASA control character ‘1’), and the line count 
will be reset. 


Output is directed to the file with ddname SYSPRINT. If the file 
is undefined or incorrectly defined, no output is produced, but no 
diagnostic indication is given. The DD statement for SYSPRINT is 
described in the Operating Reference Manual. The call made to the File 
Handler refers to the output file by name without the use of a File 
Handler work area, thus causing the File Handler to bypass the use of 
the Dispatcher to accomplish multi-tasking; control is retained in the 
calling program path. 


Coding format: 
[symbol] CALL IJKPRINT, (print-line) ,VL,MF=(E, list) 
where: 
print-line is the address of the format V record (line-image) to 


be directed to SYSPRINT. (Variable-length record formats are 
described in Chapter 6.) 
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9.9.2 IJKTRACE - Print Dispatcher Queues 


This subroutine constructs print line images producing a 
formatted display of all Dispatcher task queues. It is called 
automatically whenever the program check handler (SPIESNAP) is entered, 
or a subsystem time-out occurs, and may also be called for diagnostic 
purposes by any other program. 


Control is retained in the current program path for the duration 
of processing by this module; the dispatcher is not entered and no 
other system work is performed. 


Coding format: 
[symbol] CALL IJKTRACE 


Each print line image is passed to the module IJKPRINT for output 
to the SYSOUT data set called SYSPRINT. The Operating Reference Manual 
details the exact format of IJKTRACE output. 


9.9.3 IJKDELAY - Request Time Delay 


This module may be called to introduce a timed delay averaging 
100 milliseconds into a program path. The Dispatcher is given control 
to perform other processing and returns at the expiration of the delay 
interval. 


This facility may be utilized to give a time-slicing effect 
within a routine which would otherwise monopolize the use of CPU time. 
It can also force the buildup of parallel program paths for reentrancy 
testing purposes in an environment which otherwise might not result in 
actual parallel execution, or it may be invoked to await the passing of 
a temporary condition which will be resolved by another scheduled 
program. 


Coding format: 
[symbol] CALL IJKDELAY 
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9.10 IN-CORE TABLE SORT FACILITY (CINTSORT) 


To sort an in-core table, the INTISORT Facility is provided. Such 
a table might be data stored in a Store/Fetch string or file data 
record via online transactions or offline processing. The table can 
have any number of fixed-length entries up to 32767, and each entry can 
have a total size of 1 to 255 bytes. The key to be sorted on can be 
anywhere within the entry, but must be in the same place, and of the 
same length, in each entry. Coding format: 


[symbol] CALL INTSORT, (entries,entry-length,table,key-offset, 
key-length) , VL,MF=(E, list) 


where: 


entries is a fullword (aligned) containing the number of table 
entries (up to 32767). 


entry-length is a fullword (aligned) containing the size of each 
entry (up to 255). 


table is the address of the area containing the table to be 
sorted. 


key-offset is a fullword (aligned) containing the offset (-1) of 
the key within each entry (value must be zero if at the beginning 
of the table entry). 


key-length is a fullword containing the length of the key (to be 
sorted on) of each entry (can be the same as entry-length). 


The return code is a fullword binary value returned in register 15, as 
listed in Figure 47. For all non-zero return codes, the sort is not 
executed. 


Meaning 


Se a errs ey = ——- SSS Se SS 


INTSORT completed successfully 


Number of entries less than 1 or more than 32767. 
Length of an entry is less than 1] or greater than 255. 
No table address supplied. 

Key-offset greater than 254. 


The key-length plus key-offset exceeds maximum (255) 
entry-length. 


Figure 47. INTSORT Return Codes 
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( 9.11 OTHER INTERCOMM SERVICE FACILITIES 


The following service routines for application programs are 
accessed via the following subroutine entry names: 


e MMU (MAPIN, MAPOUT, MAPEND, MAPCLR, MAPURGE, MAPFREE) 

e Store/Fetch (INTSTORE, INTFETCH, INTUNSTO) 

e DDQ (QBUILD, QOPEN, QREAD, QREADX, QWRITE, QWRITEX, QCLOSE) 

e Page Facility (PAGE) 

e DBMS (DBINT) - data base interfacing 

@ Dynamic File Allocation (ALLOCATE, ACCESS) 

® ESS operator-id checking (SECUSER) 
Detailed documentation for use of the above facilities is provided in 
separate manuals (see Chapter 2). Special coding and call conventions 
for specific data base support are described in Data Base Management 
System Users Guide and vendor manuals. 


Macros to access other system routines and services are described 


in Chapter 10. In addition, the following facilities may be of 
interest: 
ba e Assigning a verb to a terminal (see Chapter 8) 


e Locating a Csect (and Entry) name from a hexadecimal address 
(IJKWHOIT - see Operating Reference Manual). 


e Generating a system command message (see System Control 
Commands ) 


e Generating a display or printout of dynamic storage 
(save/work area) during program execution via the SCTL system 
control command (Release 10 only). Acquire and initialize 
storage for the command message and queue it for the SYSCNTL 
subsystem (as released, SUBH=000, SUBC=C). Use the form: 


SCTLSDSPCHSaddress(len) [$address(len)...]$TID=name@ 


See the Release 10 System Control Commands for syntax details 
and length restrictions. Use the HEXCON or LAYOUT macro to 
convert a binary address to a printable hex format in the 
message text. Omit the TID parameter if the storage is to be 
displayed at the subsystem’s input message terminal. 
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9.12 LOADING SERVICE ROUTINE ENTRY POINTS FROM THE SPA 


Several Intercomm service routines may optionally be assigned to 
the Link Pack Area. (Refer to the Operating Reference Manual. ) In 
such cases, the service routine entry point should not be coded in the 
CALL macro; rather, the address of the service routine is loaded from 
the SPA or SPAEXT into register 15, and the CALL macro is coded with 
register notation, as follows: 


L R15,SPA... load service routine address from SPA 
or 

L R15 ,SPAEXTAD point to SPA Extension 

USING SPAEXT,R15 set addressability 

L R15,SEX... load service routine address from SPAEXT 
then 


CALL (15), (parameters) ,VL,MF=(E, list) 
DROP R15 cancel SPAEXT addressability 


Appendix D lists the SPA and SPAEXT field names for service routine 
entry points referenced in this manual. For dynamically loaded 
subsystems, this sequence of instructions saves dynamic linkedit time 
at Intercomm startup, unless the subsystem has been linked with the 
INTLOAD system program which performs a similar function. 


The above coding sequence may not be used if the subsystem is 
eligible for loading above the l6meg line under MVS/XA or ESA; service 
routine entry names must be used. Mode switching is accomplished by 
linking the subsystem with INTLOAD (also contains XA interface code). 
Also, do not code the SPA or SPAEXT parameters on any Intercomm macros 
except the LINKAGE and SUBLINK macros. 
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10.1 INTRODUCTION 


Intercomm provides many macro instructions to facilitate coding 
of user Assembler Language programs (subsystems, subroutines, user 


exits). 


Coding specifications for each macro are detailed in Basic 


System Macros, which should be referenced in conjunction with this 


chapter. 


Several different categories of macros are provided: 


Basic macros for subsystem structure (LINKAGE, RTNLINK, 
STORAGE, STORFREE), discussed in Chapter 3. 


Macros to simplify program coding, virtually self- 
explanatory in their use: 


-- CALLIF Conditional call, transfers control if 
subroutine is linkedited in the 
Intercomm load module 


-- CALLOVLY Call a subroutine which may be 
linkedited within the transient 
subroutine overlay region 


-- DDNFIND Test presence of a ddname in execution 
JCL 
-- EXMVE Extended MVC to move n characters, where 


n may be greater than 256 


-- EXSS Execute a storage-to-storage instruction 

-- EXTRT Extended translate and test 

-- GETDATE Get current date from CPU (yyddd) 

-- GETSPA Find Intercomm SPA address (Link Pack 
Area module) 

-- HEXCON Convert data from binary to printable 
hexadecimal 

-- INTTIME Optimized TIME macro to request CPU 
time, date 

-- LAYOUT Transfer data fields to a contiguous 
area of core, effecting conversion of 
format 

-- MSGHDR Establish symbolic names for the fields 


in Intercomm’s message header 
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REGA, REGS 
ROUND 


SECTEST 


SSCONV 


SSSTART 


SSSTOP 


SSTEST 


SUBLINK 


XASWITCH 


PMISNAP 
PMIWIO, PMIWTOR 


USRTRACK 


Intercomm Macros For 
Assembler Programs 
Generate register name equates 
Round a register value to a power of 2 


Test user function authority under ESS 
(Extended Security System) 


Convert subsystem codes to printable 
form 


Start a STRT/STOP function under program 
control 


Stop a STRT/STOP function under program 
control 


Test for bit settings controlled by the 
General Purpose Subsystem 


Provide subroutine linkage (similar to 
LINKAGE macro). Note: can be paired 
with the RINLINK macro 


Switch MVS/XA address modes (24/31) 


functions: 
Issue a snap 
Issue a WTO (WTOR) 


Track user data for SAM (System 
Accounting Facility) 
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e Macros which request system control functions to be 


performed: 
-- DISPATCH 


-- INTWAIT 


-- INTPOST 


-- PASS, CATCH 


-- INTENQ, INTDEQ 


-- SUBTASK 


-- MODCNTRL 


Create or cancel a Dispatcher task 


Wait on event completion, or request a 
timed processing delay 


Post internal event 
Transfer control of a system resource 
for a message processing thread to or 


from the Intercomm system (thread 0) 


Enqueue/dequeue request for exclusive or 
shared control of a resource 


Create an application program subtask 


Request LOAD/LINK/DELETE of a user 
subroutine defined in REENTSBS table 


The macros used for debugging and to request system control 
functions are described in alphabetical order. Illustrations of the 
use of several of these macros for system control functions conclude 


this section. 
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10.2 MACRO DESCRIPTIONS 


10.2.1 CATCH -- Transfer Ownership of a Storage Area from 
Intercomm to an Application 


The CATCH macro is issued by an application, in a system with the 
Resource Management Auditing and Purging facility in use, to take 
control of an area of storage belonging to Intercomm. CATCHing an area 
ensures that it will be freed by the Resource Management purge routine 
if the subsystem program checks or times out. 


10.2.2 DISPATCH -- Request Multithread Dispatcher Queuing Service 


The DISPATCH macro provides the facility for requesting one of 
several queuing services from Intercomm’s Multithreading Dispatcher. 
The following types of service requests are available: 


e A request for a unit of work to be placed on a specific 
priority execution queue and executed as soon as priority 
permits 


e A request for a unit of work to be placed on a timer queue 
and executed upon the elapse of a specified duration of time 


e A request for a unit of work to be placed on an event queue 
and executed upon the completion of a specified event 


e A request to delete (cancel) a previously queued request 


@ A request to terminate control and initiate processing by the 
highest priority unit of work awaiting execution 


Three kinds of queues exist: event, timer and execution queues. 
There are two event queues, one timer queue, and four execution queues, 
corresponding to the highest-lowest Intercomm priority codes of 0, l, 
25: 3 All units of work placed on an event or timer queue remain 
queued until the event transpires or the duration expires. They are 
then, depending upon assigned priority, transferred to one of the 
execution queues. 


The INTWAIT macro may be used in lieu of the DISPATCH macro for 
timer or event waiting. 


NOTE: The IBM STIMER and TTIMER macros are not allowed to be 
issued by any user program. 
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10.2.3 INTDEQ -- Dequeue 


The INTDEQ macro is used in conjunction with the INTENQ macro in 
order to signal to the enqueuing-dequeuing module that a requestor, 
having already been INTENQed and subsequently granted access to a 
resource, has no further need of that resource. For every INTENQ macro 
issued for a resource, there must be an INTIDEQ macro’ subsequently 
issued for the same resource. If, after the issuance of an INTDEQ 
macro, the enqueuing-dequeuing module identifies a requestor as having 
been previously INTENQed, and not having timed out, register 15 will 
contain a return code of 0. If, however, a previous INTENQ was not 
issued, or if the previous INTENQ request timed out, register 15 will 
contain a return code of 4. 


10.2.4 INTENO -- Enqueue 


The INTENQ macro is used in conjunction with the INTDEQ macro to 
serialize the use of a particular resource and, if necessary, delimit 
the number of concurrent users of that resource. The INTENQ macro is 
essentially a request to be placed upon a resource queue. Control is 
not returned to the issuer of INTENQ until all previous requestors on 
that queue have been given resource access. However, if the SHARE 
parameter is coded, all previous requestors may or may not have 
dequeued themselves by the time control is received. When a requestor 
is placed upon a queue, all registers are saved, therefore register 13 
must point to a save area. The INTENQ macro expansion uses registers 
O, 1, 14 and 15. No return code is employed, except if the TEST option 
is used. 


10.2.5 INTPOST -- Post Internal ECB 


The INTPOST macro is used to post an ECB awaited via the 
INTRNL=IPOST option of the DISPATCH or INTWAIT macros. This provides 
the most efficient synchronization technique for two threads within the 
same Intercomm task. INTPOST may also be used when INTRNL=YES was 
specified on the DISPATCH or INTWAIT macros. If the object ECB is 
already posted, then no over-posting will take place. 


10.2.6 INTWAIT -- Temporarily Relinguish Control 


The INTWAIT macro causes the issuing module to temporarily 
relinquish control until either an ECB is posted or a time interval 
expires. It assumes only that the caller’s register 13 is pointing to 
a save area. 
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This macro is a convenient way to replace the following 
frequently occuring coding sequence: 


STM 14,12,12(13) 
DISPATCH ‘'S’,label,(13),EXIT,{ECB= ) 
{ INTVL=) 


label LR 13,1 
LM 14,12,12(¢€13) 


10.2.7 MODCNTRL--Control Dynamically Loaded Subroutines 


The MODCNTRL macro requests loading or linking, and then 
deleting, of separately linkedited user-written load modules. The 
referenced subroutines or tables must be defined using the SUBMODS 
macro within the REENTSBS table. Register 15 is set to X'FFFFFFFF' 
when the SUBMODS entry cannot be found, or if the requested module is 
not available. No other return code is set in register 15. If the 
module may be loaded above the l6meg line under XA, a requesting 
program executing in 24-Amode is responsible for address mode switching 
using the XASWITCH macro when the LOAD option is used. 


10.2.8 PASS--Transfer Ownership of a Storage Area from an 
Application to Intercomm 


The PASS macro is used, in a system with Resource Auditing and 
Purging, to protect an area of core acquired by an application thread 
from being freed by the purge routine when the thread completes. That 
is, the ownership is passed to the Intercomm system thread (thread 0). 
(See also STORAGE macro, SYS parameter). 


10.2.9 PMISNAP--Issue a Snap 


The PMISNAP macro should be used by subsystems in place of the 
IBM SNAP macro. It deducts the time taken by the snap operation from 
total elapsed time, thereby avoiding a subsystem time-out which could 
occur when taking a snap. 


10.2.10 PMIWIO--Write to Operator 


The PMIWTO macro generates a parameter list and call to the 
Intercomm module WIOMOD, which centralizes all WTOs to the CPU console, 
and/or the control terminal, and/or SYSPRINT, based on macro coding 
options. Do not use the PMIWTO macro if issuing a multiline WTO; use 
the IBM WIO macro. 
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10.2.11 PMIWIOR--Write to Operator with Reply 


The PMIWTOR macro generates a parameter list and calls the 
Intercomm module WTOMOD. The program issuing the macro may regain 
control after the reply takes place by issuing a DISPATCH or INTWAIT 
Macro to wait on the ECB specified in the macro parameters. If issuing 
a multiline WIOR, do not use this macro; use the IBM WTOR macro. 


10.2.12 SUBTASK--Dynamic Subtasking 


The SUBTASK macro allows part of a thread's logic to execute as a 
MVS subtask. The program linkage between the main Intercomm task and 
the subtasked logic may be viewed as being equivalent to a call to a 
subroutine. Registers 1 and 13 can be used as if a call was issued. 
SUBTASK generates the instruction BALR 14,15 with Register 15 
containing the ENTRY parameter value. 


All registers are passed from the main task portion of the 
application subsystem to the subtask. Intercomm suspends execution of 
the SUBTASKing thread (via DISPATCH WAIT) until the subtasked code 
completes, but other threads, perhaps of the same subsystem, may be 
processed by the main task during this time. When the subtasked code 
completes, register contents when the SUBTASKing thread is redispatched 
depends upon what action the subtasked code took to save and restore 
them. 


The subtasked code can be a piece of code in the application 
subsystem itself or an external subroutine. The main use of the 
SUBTASK macro is to allow code which may impede Intercomm performance 
to be executed in a subtask, instead of slowing the main task. 
Usually, the code would include SVCs with implied WAITS in them. For 
example, if an application subsystem wanted to issue a LOAD macro, 
SUBTASK could be used to allow the main task to continue while the 
subtask would be held up by MVS until the LOAD completed. The 
Intercomm File Handler subtasks the issuance of QSAM GETS in this 
manner, 


A SUBTASK macro may not be issued by any program eligible for 
loading above the l6meg line under XA. 


10.2.13 USRTRACK-- Track User Data Using SAM 


If the System Accounting and Measurement Facility (see Operating 
Reference Manual) is installed and activated for the subsystem (SYCTTBL 
macro, SAM parameter), this macro can be used to increment a 
user-defined accumulator (for Data Base calls, for example) or to 
invoke a user SAM exit routine. 
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See Chapter 3 regarding usage of macros by programs loaded above 
the l6meg line. 


10.3.1 DISPATCH Macro Usage 


The following coding examples show several uses of the DISPATCH 
macro. 


In the first example, the programmer wishes to allow other tasks 
to continue execution while this routine waits for the completion of an 


event (an input/output operation, for example). Assume that the ECB 
address has been previously loaded into general register 8: 


*USING DISPATCH TO WAIT FOR AN EVENT 


WAIT STM 2,12,28(13) SAVE REGISTERS 


DISPATCH 'S’, DONE, (13) , EXIT, ECB=(8) 
DONE LR A Sig: RESTORE REGISTER 13 
LM 2,12,28(13) RESTORE REGISTERS 


The routine in progress uses its own save area to store all necessary 
registers before exiting, and restores the registers after regaining 
control. The address of the program’s save area is the parameter 
passed through the Dispatcher. This example is reentrant. Note that 
this code could be replaced by an INTWAIT macro. 


In the second example, the programmer wishes to allow other tasks 
awaiting CPU time to be dispatched, returning to this routine after the 
execution of higher or equal priority tasks which were awaiting events 
that may by now have been completed, or after the execution of equal or 
higher priority tasks which this routine may have just previously 
placed on the Dispatcher execution queue. The programmer wishes to 
give this task the same priority it had received when it gained control 
(‘S’ parameter): 


*USING DISPATCH FOR TASK ROTATION 


ROTATE STM 2,12,28(13) SAVE REGISTERS 


DISPATCH 'S', RESUME, (13) , EXIT 
RESUME LR alee ame RESTORE REGISTER 13 
LM 2,12,28(13) RESTORE REGISTERS 
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In the third example, the programmer wishes to schedule the 
execution of a subprogram which will be executed concurrently with the 
program or after the program terminates, depending upon Dispatcher 
scheduling. Assume that the address of a calling program parameter 
list has been preloaded into general register 1: 


*USING DISPATCH TO SCHEDULE SUBPROGRAM 


L 0,=V(SUBPROG) 
SCHED DISPATCH 'S’, (0), (1) , SYS=YES 


The execution of this program continues. The subprogram gains control 
after this program returns to the Monitor, or if this program gives up 
control in any way (1/0 operation through the File Handler, task 
rotation, etc.). The SYS parameter ensures that the dispatched routine 
will not be purged from its execute queue if the issuing program 
completes before the subprogram is given control. Note also that the 
passed parameter list, and the parameter values, may not be in dynamic 
storage owned by the issuing program (see also STORAGE and STORFREE 
macros, SYS parameter). The dispatched subprogram will receive control 
in thread zero (0), and execute as a system program. 


In the fourth example, the programmer does not wish to continue 
processing until three events (ECB1, ECB2, and ECB3) have all 
completed. Control returns to the issuing program when all three ECBs 
have been posted: 


*USING DISPATCH FOR A MULTIPLE WAIT 


MULTWAIT DISPATCH 'S' ,COUNT, (13) , ECB=ECB1 
DISPATCH 'S' , COUNT, (13) , ECB=ECB2 
DISPATCH 'S’ ,COUNT, (13) , ECB=ECB3 
LA 12,3 SET COUNTER TO 3 


STM 2,12,28(13) SAVE REGISTERS 

DISPATCH EXIT EXIT 

LR 13,1 RESTORE REGISTER 13 

LM 2,12,28(13) RESTORE REGISTERS 

BCT 12 ,WAIT DECREMENT COUNTER & 
BRANCH NOT ZERO 
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10.3.2 PASS/CATCH Macro Usage 


One subsystem acquires (and initializes) an area of core (by 
issuing a STORAGE macro) and passes the address of that core via 
message switching to another subsystem. 


Subsystem A Subsystem B 


GET STORAGE ADDRESS FROM 
INPUT MESSAGE 
L R/7 ,area-address 
CATCH LEN=256 , ADDR=(R7) 


STORAGE LEN=256,ADDR=(R1), 
LIST=PARMSAVE 
LR R11,R1 


PROCESS AS IF THE AREA HAD 
BEEN ACQUIRED BY THIS SUB- 
SYSTEM 


INITIALIZE STORAGE AREA 


CREATE MESSAGE FOR SUBSYSTEM 
B WITH ADDRESS OF ACQUIRED 
CORE IN THE MESSAGE TEXT 


PASS LEN=256 , ADDR=(R11) 


QUEUE THE MESSAGE 


CALL MSGCOL, STORFREE  LEN=256,ADDR=(R7) 


NOTE: the PASS macro would be redundant if the storage was acquired 
using the SYS=YES parameter. However, if the subsystem program 
checked or timed out, the acquired storage would not be freed 
and would be permanently allocated. Use the PASS and the call 
to MSGCOL at the end of the program (just before the RTNLINK). 
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10.3.3 INTENQ/INTDEQ Macro Usage 


One subsystem updates a table entry in USERSPA. During the time 
of this update, other subsystems should not be allowed access to the 
table. All subsystems must use the same resource identification. The 
update subsystem has exclusive control during the time of the update; 
the access subsystem merely tests to ensure that exclusive control is 
not in effect before accessing the updated table area, as follows: 


Update Subsystem Access Subsystem 


* ENQUEUE RESOURCE 
LA R6,TABLENQ 
INTENQ (R6) 


* TEST IF RESOURCE ENQUEUED 
LA R4, TABLENQ 
INTENQ (R4) 
INTDEQ (R4) 

* ACCESS TABLE DATA 


* PERFORM TABLE UPDATE 


* DEQUEUE RESOURCE 
INTDEQ (R6) 


TABLENQ DC CL16’USERTABLE' TABLENQ DC CL16'USERTABLE' 


10.3.4 MODCNTRL Macro Usage 


A user routine for error processing (ERRORRIN) is infrequently 
used. Therefore, it might be defined in REENTSBS as a routine eligible 
for dynamic load. A subsystem calling this routine might be coded as 
follows: 


*LOAD or LINK must be paired with DELETE 
MODCNTRL MODNAME=ERRRTN , ACTION=LOAD 
LTR R15,R15 
BNZ NOLOAD 
LR R15,R1 address of routine 


CALL (15) , (parameters -for-ERRORRTN) , VL,MF=(E, list) 
MODCNTRL MODNAME=ERRRTN , ACTION=DELETE 
NOLOAD ODS OH 


CL8 ‘ ERRORRTN' 
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SAMPLE PROCESSING PROGRAMS 


The sample program SQASMA, shown in Figure 48, demonstrates 
coding of a BAL subsystem which is either resident or dynamically 
loadable below the l6meg line (if MVS/XA or ESA). The program 
processes an inquiry transaction (MURA) containing a part number and a 
warehouse number for a stock status display. MMU is used to transform 
the incoming message into a fixed field format. The part number is 
transformed into a RBN for accessing a BDAM part description file 
(PARTFILE). The RBN and a part description record area are passed as 
parameters to a called BAL subroutine SQASMB, illustrated in Figure 49, 
which also resides below the l6meg line. The subroutine retrieves the 
requested record from PARTFILE and passes back the File Handler return 
code to the calling subsystem via register 15. 


Together, the part number and warehouse number provide a VSAM key 
for accessing a stock status file (STOKFILE). The File Handler is used 
for accessing both files. MMU is used for formatting an output 
display. Error messages, for conditions such as non-existent or 
erroneous warehouse or part numbers, or file I/O errors, are built 
within the program and formatted by MMU using an error map area. 


The MSGHDRC source text member defining the Intercomm message 
header fields is COPY’d from the Intercomm source library (SYMREL) by 
the Assembler. The ASMLOGCH source text member used for terminal 
attribute and command override for MMU processing, and the symbolic map 
areas, are also copied into the program. 


All required table entries, JCL, sample input messages and 
testing procedures, plus sample execution output, are illustrated in 
Chapter 12, "Subsystem Testing." The subsystem code used in the 
SYCTTBL macro to identify the sample subsystem is RA. Intercomm’s BTAM 
simulator is used for testing. Test messages are included to test as 
Many error combinations as possible. Chapter 13 illustrates a similar 
subsystem (without the subroutine) coded for the same purpose but using 
the Edit and Output Utilities, a MSGCOL call, and Test Mode for 
testing. 
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SAMPLE REENTRANT ASSEMBLER SUBSYSTEM USING THE FILE HANDLER 
TO ACCESS A VSAM FILE AND SUBROUTINE SQASMB TO ACCESS A BDAM 
FILE. MAU IS USED FOR INPUT AND OUTPUT MAPPING AND MAPPING 
ERRCR MESSAGES. 
- REGISTER USAGE - 


1/0 MAP 

WORK 

RETURN CODE 
ERROR MAP 

BAL INSTRUCTIONS 
BAL INSTRUCTIONS 
PARMS. 

INPUT PESSAGE 
SPA 

SPAEXT 

BASE REGISTER 
SAVE AREA (WORKAREA DSECT) 


el al i ok ae 
NOUS WNP OWDATNAW RW 


bm pe 
0 @ 


PRINT NOGEN 
SQASMA CSECT 
LINKAGE BASE=(RC)9SPA®(RA) »sLEN#=DYNLEANsGPREQSREGA, 
MSG#(RS) sPARM=(RB8) 
PRINT NOGEN 
PRINT NOGEN 
PRINT GEN 
PUSH PRINT TURN OFF PRINT GENERATION 
PRINT NOGEN 
POP PRINT RESUME PRINT GENERATION 


Figure 48, Sample Reentrant Subsystem (Assembler) (Page 1 of 15) 
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PRINT NOGEN 
USING INMSGsR9 
USING WORKAREA,RD 
USING STKSTATsR2 
USING SPAEXT,RB 
XR R49R4 INITIALIZE RETURN CODE 
LA RS5ygWORKLEN*MAPIL(9RD) ADDRESS ERROR MAP 
RBy»SPAEXTAD 
R6sMOVEHDR MCVE INP HDR TO QUTP HDR 
R6sMAPIN MAP AND THEN FREE THE INPUT MSG 
REsPRERTN WHERE TO RETURN 
MCwW,C'3° IF A FIELD IS IN ERROR 
$24 INVINPUT SEND ERRCR MSG 
925 MCW,C°O* IF MAPPING NOT OK 
926 MAPER SEKD ERROR MSG 
927 R6,CLEARMAP CLEAR THE MAP 
$28 R6eRDPARTFL PREPARE 70 READ PARTFILE 
929 R6sBOAMREAC READ A RECORD 
930 ! FHFLAG,sBORDOK READ OK? 
931 PRERTN NO 
932 R6ysROSTKFIL PREPARE TQ READ STOCK FILE 
933 R65 VSAMREAD READ A RECORD 
934 FHFLAG,VSROOK READ OK? 
935 PRERTN NO 
$36 R69MAPOUT PREPARE OUTPUT MAP 
937 MCwWsC"O" OK? 
938 PRERTN YUP 
$39 R69MAPER NO.»SEND ERROR MSG 
940 PRERTN OH 
941 MAPFLGyNOMAP UNABLE TO SEND MAP? 
942 RETURN YES - JUST FREE MAP AND GO 
943 R6sRETURN WHERE TO RETURN 
944 MAPFLG»MAPERR ARE WE SENDING AN ERROR MAP? 
$45 ERMAPEND YES = GO DO IT 
946 BAL R6,GDMAPEND SEND GOOD MAP 
947 RETURN 0S OH 
$48 444 FREE INPUT MAP AREA AND RETURN 
$49 XC MCWo MCW CLEAR MAP CONTROL WORD 
950 CALL MAPFREE» (MCWeTOGRP» IOMAP sADDRMSG yCMSGHTID)» 
VLoMFe(E sCALLIST) 
965 RTNLINK ADDR#(RD) »sLEN*DYNLEN »RC8(R4) 
975+ PRINT NOGEN 
1Cl1+*,GETSPA = V7.0 = 11/76 = SM 


Figure 48. Sample Reentrant Subsystem (Assembler) (Page 2 of 15) 
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1035 
1036 
1037 
1038 
1039 
1040 


1042 
1043 
1044 
1045 


1060 
1061 


1C63 
1C64 
1€65 
1066 


1082 


1083 
1084 
1085 
1C86 
1087 
1C88 


1090 
1091 
1C92 
1€93 


1108 
1109 
1110 
1111 
1112 
1113 
1114 
1115 
1116 
1117 
1118 
1119 
1120 
1121 
1122 


MOVEHDR ODS 
MVC 


MAPIN DS 


BR 


CLEARMAP DS 
XC 
MVI 


RDPARTFL DS 
PACK 
CVB 
ST 
MVC 
BR 


BDAMREAD DS 


** LSE MOOCNTRL MACRC TO LINK TO SCASMB SUBRTN WHICH READS A BDAM FILE 
MCVE SUBRTN NAME INTG WORK AREA 


MVC 


OH 


OMSGHTID sMSGHTIO 


IOGRP, IOGRPNM 
TOMAP,IOMAPNM 
ERMAP,ERMAPNM 
R6 


OH 
R9,ADDRASG 
MCW(4),MCW 


Sample Processing Programs 


SAVE TID 


MOVE MAP GROUP NAME TO WORK AREA 


MOVE MAP NAME 
MOVE ERR MAP NAME 


STORE INPUT MSG ADDRESS 
CLEAR MAP CONTROL WORD 


MAPIN, (MCB a ITOGRP » IOMAP sADDRMSG MCW) VL 


MFe(E,CALLIST) 
R2,ADDRMSG 
R6 


OH 
MCW(4) MCW 
MCWOPT4,CPA® 


MAP INPUT MESSAGE 
MAPPED MSG DATA ADDRESS 


CLEAR MAP CONTROL WORD 


ONLY CLEAR ATTRIBUTE BYTES 


MAPCLR» (MCW sTOGRP» IOMAP yMAP1,OMSGHTID) »VLy» 


MFe(E,CALLIST) 
R6 


OH 
DWORDsRBNBYTE 
R3sDWORD 
R3sRBNWORD 


CURRF ILE sDOPART 


R6 


OH 


SUBNAMEsSQ4SMB 


PACK RBN # 

AND CONVERT TC BINARY 
STORE RBN 

DDNAME OF BDAM FILE 


MODCNTRL €PARTRECsRBNWORD) » VLoMF@tEsCALLIST), 
ACTIGN#=_INKsMOONAME=SUBNAME 


LTR 
BM 


SUBOK DS 


Figure 48, 


RF 9 RF 
NOSUBRTN 

*+4 (RF) 

SUBQK 

IOERROR 
NOTFOUND 

NODOD 

OH 
RECPIN,PARTNO 
NOTFOUND 
PRIDATAsRECDES 
ORDUN T»RECUNT 
PRTIPRC »RETPRCE 
FHFLAG »,BDORCOK 
R6 


DID SQASMB GET CONTROL? 
NO 

BRANCH ON RETURN CODE 
O RC 

4 RC 

8 RC 

12 RC 


CORRECT RECORD? 

NO 

MOVE CATA TO OQUTP MS 
Be 


Wi n " of 
ee oe iL) Ty 


SHOW EVERYTHINGS OK 
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1124 
1125 
1126 
1127 
1128 
1129 


1131 
1132 
1133 
1134 
1135 
1136 
1137 
1138 
1139 
1140 
1141 
1142 
1143 
1144 
1145 
1146 
1147 
1148 
1149 
1150 
1151 


1152 


1153 


1155 
1156 
1157 


1171 


1173 
1174 
1175 
1187 


1189 
1190 
1191 
1202 


ROSTKFIL DS 
MVC 
MVC 
MVC 
MVC 
BR 


VSARREAD OS 


DORLSE OS 


VSREAD2 ODS 


SELECT DS 


RELEASE DS 


Sample Processing Programs 


OH 

CURRFILE»,ODSTOCK GET DONAME OF FILE 
RECWHS » WHSNO FIND KEY OF RECORD WE WANT 
RECPNO ,»PARTNO 

KEYFIELDsKEYFLD AND MOVE IT INTO KEY AREA 
R6 

QOH 

EXTOSCT(48),EXTDSCT CLEAR IT 

R7,SELECT GO SELECT THE FILE 
FHSTAT1,C'S' NO OD? 

NODD 

R7,VSREAD2 READ A RECORD 
FHSTAT1sC'1'" I/O ERROR? 

IDERROR YES 

FHSTAT1I»C'2" RECORD NOT FOUND? 
VSRECNF NOT FOUND = GO BUILD ERROR MSG 
FHFLAGsVSRCOK INDICATE READ wORKED 
WHSLOCsRECWLC BUILD OUTPUT PESSAGE 
STKLEV,RECLEV 

DATEDIT»RECLOT 

R7,EDITDATE MAKE DATE PRINTABLE 
LEVDATE sDATEMOVE 

STKORD »sRECORD 

DATEDIT »RECODT 

R7,EDITDATE MAKE DATE PRINTABLE 
ORDDATE sDATEMOVE 

OH 

R7sRELEASE GO RELEASE THE FILE 
R6 

OH 

FHSTAT »FHSTAT CLEAR FH CONTROL WORD 


GETVs (EXTOSCTsFHSTAT sSTOCKREC »KEYFIELD) + 
VLoMF@(EsCALLIST) 


R7 RETURN TO SUBRTN 

OH 

FHSTAT,FHSTAT CLEAR FILE FANDLER CONTROL WORD 
SELECT, CEXTOSCTsFHSTAT »sCURRFILE) »VLyMF@(E  yCALLIST) 
R7 RETURN TO SUBRTN 

OH 

FHSTAT,FHSTAT CLEAR FILE FANDLER CONTROL WORD 
RELEASEs (EXTDSCTsFHSTAT) »VLyMFS(E yCALLIST) 

R? RETURN TO SUBRITN 


Figure 48. Sample Reentrant Subsystem (Assembler) (Page 4 of 15) 
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1204 EDITDATE DS 


1205 
1206 
1207 
1208 
1209 
1210 


1212 
1213 
1214 
1215 
1216 
1217 
1218 
1219 
1220 
1221 
1222 
1223 


1225 
1226 
1227 
1228 
1229 
1230 
1231 
1232 
1233 
1234 


1236 
1237 
1249 


1251 
1252 
1262 


1264 
1265 
1266 


1282 


Figure 48. 


GDMAPEND 


ERMAPEND 


MAPEND 


MAPURGE 


MAPOUT 


AYC 
MVC 
MYC 
MVC 
MVC 
BR 
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OH EDIT DATE TO MM/DD/YY FORM 
DMYEAR,DEYEAR 

SLASH1»SLASH 

OMDAY»DEDAY 

SLASH2 SLASH 

DMMC DEMO 

R? RETURN TO SUBRTN 

OH 

MCW MCW CLEAR MAP CONTROL WORD 

MCWOPT29C'C! TRANSMIT ENTIRE MSG 

R7 »MAPEND GO CALL MAPEND 

MCWsC'B MAPEND SUCCESSFUL? 

R6 YES 

R7 sMAPURGE NO.wsPURGE THE MAP 

Ro SAVE SAVE THE LINK REGISTER 

R6sMAPER PREPARE AA ERROR MSG 

RoyERMAPEND SEND THE ERROR MSG 

RO»SAVE RESTORE LINK REGISTER 

R6 RETURN TG MAINLINE 

OH 

MCwy MCW CLEAR MAP CONTROL WORD 

MCWOPT2,C'C! TRANSMIT BSG 

MCWOPT3,WRITE] OVERWRITE EXISTING SCREEN 

R7»MAPEND GO CALL MAPEND 

MCWsC'S! SUCCESSFUL? J 
R6 YES 

R7 »MAPURGE NOeePURGE THE MAP 

R4,8 RETURN CODE = 8 

RE RETURK TO MAINLINE 

OH 

MAPEND, (ACB, OoMCW) op VL eMFeCEsCALLIST) 

R? RETURN TO SUBRIN 
OH 

MAPURGEs (MCB) 9 VL» MF#(E »CALLIST) | 
R7 RETURN TO SUBRTN | 
OH 

MCW» MCW CLEAR MAP CONTROL WORD 

MAPDUT, (MCB, IOGRP» ICMAPsMAP1,MCHyOMSGHTID) 5 - 
VL »MFe(E,CALLIST) 

R6 RETURN TO MAINLINE 


Sample Reentrant Subsystem (Assembler) (Page 5 of 15) 
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1264 *#** ERROR ROUTINES #48 


1285 * 

1286 *# 

1287 * 

1266 DROP R2 

1289 USING ERRMAP,»R5 

1290 INVINPUT DOS OH 

1291 CLC PARTNOT=MAP1(19R2) s>WHSNOT=MAP1(R2) BOTH NON-NUMERIC? 
1292 BNE ONLY1 NO = CNLY 1 IS 

1293 MVC MSG79MSGI MOVE IN APPROPRIATE MSG 
1294 B GOSNDMSG MAP THE ERROR MSG 

1295 ONLY1 DS OH 

1296 MVC MSG79MSGG MOVE IN APPROPRIATE MSG 
1297 BH GOSNDMSG PARTNO NOT NUMERIC 

1298 MVC MSG7 »MSGH WHSNO NOT NUMERIC 

1299 GOSNDMSG OS OH 

1300 MVC ERRMSGsINVINMSG MOVE MSG INTO MAP 

1301 BAL R7sSENDERR GO CALL MAPOUT 

1302 BR R6 RETURN TO MAINLINE 

1304 NOSUBRTN OS OH 

1305 MYC MSG8,MSGJ BUILD ERRGR MSG 

1306 MVC NOFILE,CURRFILE 

1307 MVC MSG9 »MSGK 

13086 MVC ERRMSG(L'NCSUBMSG) ,NOSUBMSG MOVE INTO MAP 
1309 BAL R7sSENDERR DO MAPOUT 

1310 BR R6 RETURN TO MAINLINE 


1212 VSRECNF ODS OH 


1313 MYC MSG3sMSGC NOT FOUND = BUILD ERROR MSG 
1314 MYC MSG4 »MSGD 

1315 MVC NOWARENO sPARTAC=MAP1(R2) 

1316 MVC NOWARWHS »WKSNO-MAP1(R2) 

1317 MVC ERRMSG(37)sNOWARMSG MOVE MSG INTO ERROR MAP 
1318 BAL R7sSENDERR GO MAP ERROR MESSAGE 

1319 B DORLSE 


1321 NOTFOUND DS OH 


1322 MVC MSG1l»MSGA BUILD ERROR MSG 

1323 MYC MSG25MSGB 

1324 MYC NOPARTsPARTNO=MAP1(R2) MCVE IN MISSING PART # 
1325 MVC ERRMSG(L'NOPRTMSG) »NOPRTMSG MOVE INTO MAP 

1326 BAL R7ysSENDERR DO MAPOQUT 

1327 BR RE RETURN TO MAINLINE 


Figure 48. Sample Reentrant Subsystem (Assembler) (Page 6 of 15) 
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1329 
1330 
1331 
1332 
1333 
1334 
1335 
1336 
1337 
1338 
1339 
1340 
1341 
1342 


1344 
1345 
1346 
1347 
1348 
1349 


1351 
1352 
1353 
1354 


1370 
1371 
1372 
1373 
1374 


NODD 


IOERROR 


CONTIN 


SENCERR 


Figure 48. 
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OH 

CANCGDE»*CLi5°NO DD FOR FILE’ 

CONTIN 

OH 

FHFLAG,IOERR INDICATE AN IO-ERROR 
CANCODE,2CL15°IO ERROR ON® 

OH 

MSG5 yMSGE MOVE IN APPROPRIATE MSG 
CANFLNMsCURRFILE MOVE IN FILE NAME 
ERRMSG(L*CANMSG) »CANMSG MOVE INTO MAP 
R7,sSENDERR DO MAPOUT 
FHFLAG,BORDOK+IOERR IF IOERROR CN VSAM FILE 
DORLSE THEN GO RELEASE IT 

R6 RETURN TO MAINLINE 


OH 

MSG65MSGF MOVE IN APPROPRIATE MSG 
ERRTAG » MCW MOVE BYTES 1 &€ 2 INTO MSG 
ERRMSG(L*MAPERMSG) »MAPERMSG MOVE INTO MAP 
R7,SENDERR DO MAPOUT 

R6 RETURN TO MAINLINE 


OH 

MCWsMCw CLEAR MAP CONTROL WORD 
MAPFLG»MAPERR INDICATE MAPOUT FOR ERROR MAP 
MAPOUT,(MCB,IOGRP,»ERMAPsERRMAP »MCW,OMSGHTID), 

VL oMFe(E,CALLIST) 

MCW»sC'O® MAPOUT CK? 

R7 YES 

R458 NO = RETURN CODE = 8 

MAPFLG »NOMAP SHOW NO MAP SENT 

R? RETURN TO SUBRTN 


Sample Reentrant Subsystem (Assembler) (Page 7 of 15) 
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1376 PRINT GEN 

1377 **% CONSTANTS 

1378 SLASH OC c’s' 

1379 DDOSTOCK OC C'STOKFILE' 
1380 DDPART DC C°PARTFILE* 
1381 IOGRPNM DC CLE*STKSTAT* 
1382 ICMAPNM ODOC CL8*MAP1* 
1383 ERMAPNM DC CL8*ERRMAP * 
1384 SQASMB DC CL8*SQASMB! 
1385 MSGTBL DS OCL206 


1386 MSGA OC C*PART NUMBER ° 
1387 MSGB DC C* NOT FOUND.'* 
1288 ¥SGC OC C*PART ° 
1389 MSGC DC C* NOT FOUND IN WAREHOUSE ° 
1390 MSGE DC C'. MESSAGE CANCELLED.'* 
1391 MSCF DC C°'MAP ERROR MCW IS * 
1392 MSGG DC CL5O"INVALIO DATA: PARTNO MUST BE NUMERIC® 
1393 MSGH OC CL5O0" INVALID DATA: WHSNO MUST BE NUMERIC! 
1394 MSGI DC CL50"INVALID DATA: PARTNO AND WHSNC MUST BE NUMERIC! 
13295 MSGJ DC C*SUBROUTINE TO READ * 
1396 MSGK DC C* NOT AVAILABLE® 
1397 COPY ASMLOGCH SYMBOLIC CONTROL CHARS AND ATTRIBS.- 
1399 * LOGICAL ATTRIBUTE BYTE DEFINITIONS FOR IBM3270 
1400 * 
1401 UAN EQU 1 UNPROT/ALPFA/NORMAL 
1402 UANMDT EQU 2 UNPROT/ALPHA/MDOTON 
1403 VLANRSEL EQU 3 UNPROT/ALPHA/SELPEN 
— 1404 UANMDSEL EQU 4 
1405 UAHSEL EQU 5 
14C6 UAHMDSEL EQU 6 
1407 UAX ECU 7 
1408 UAXMDT EQU 8 
1409 UNN EQU 9 
1410 UNNMDT EQU 10 
1411 UNNSEL EQU 11 
1412 UNNMDSEL ECU 12 
1413 UNFSEL EQU 13 
1414 UNFMDSEL EQU 14 
1415 UNX EQU 15 
1416 UNXFDT EQU 16 
1417 PAK ECU 1? 
1418 PANMDT EQU 18 
1419 PANSEL EQU 19 
1420 PANMOSEL EQU 20 
1421 PAHSEL EQU 21 
1422 PAHMDSEL ESOU 22 
1423 PAX ECU 23 
1424 PAXMDT EQU 24 
-1425 PSN EQU 25 
1426 PSAMDT EQU 26 
1427 PSKSEL EQU 27 
1428 PSNPDSEL EQU 28 
1429 PSHSEL ECU 29 
( Figure 48. Sample Reentrant Subsystem (Assembler) (Page 8 of 15) 
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1430 PSFMDSEL EQU 39 


1431 PSX EQU 32 
1432 PSX#DT EQU 32 
1433 SUPR ECU 33 


1435 *# LOGICAL COMMAND CHARACTER DEFINITIONS FOR IBM3270 
1436 * 

1437 WRITE EQuU I 

1438 ERASWRIT ECU 2 

1439 ERASWRAL EQU 3 


1441 * LOGICAL COATROL CHARACTER DEFINITIONS FOR 1843270 
1442 * 

1443 RMDT EQU 
1444 RKEYBD QU 
1445 RMDTKEYB EQU 
1446 ALARM EQU 
1447 ALRFMRMDT EQU 
1448 ALRFRKEY ECU 
1449 ALRMRMKY ECU 
1450 PRNTNL QU 
1451 PRAT4O  EQU 
1452 PRAT64 EOQU 10 

1453 PRNT8O EQU 11 

1454 PRNLRMDT EQU. 12 

1455 PR4QRMDT EQU 13 

1456 PR64RMDT EQU 14 

1457 PR&CRMDT EQU 15 wat) 
1458 PRNLRKEY EQU' 16 

1459 PR4ORKEY ECU. 17 

1460 PRE4RKEY ECU 18 

1461 PRBORKEY EQU 19 

1462 PRNLRMKY EQU 20 

1463 PR4CRMKY EQU 21 

1464 PRE4ARMKY ECU 22 

1465 PRBORMKY EQU 23 

1466 PRALALRM EQU 24 

1467 PR4CALRM EQU 25 

1468 PRE4SALRM EQU 26 

1469 PRBOALRM EQU 27 

14706 PRNLARWD EQU 28 

1471 PR4CARMD EQU 29 

1472 PR64ARMD EQU 30 

1473 PRACARMD EQU 31 

1474 PRNLARKY EQU 32 

1475 PR4OARKY EGU 33 

1476 PROSARKY EQU 34 

1477 PRECARKY EQU 35 

1478 PRNLAMKY EQU 36 

1479 PR4CAMKY EQU 37 

1480 PRO4AMKY ECU 38 

1481 PRBOAMKY EQU 39 

1462 NULL EQU 40 


OOnouwl WN Pe 


J 


Figure 48. Sample Reentrant Subsystem (Assembler) (Page 9 of 15) 
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LOGICAL ATTRIBUTE BYTE DEFINITIONS FOR DS40 


UAN FCR DS40=UNPROT/ALPHA/NORMAL 

UANMDT FOR DS40=UNPROT/ALPHA/MDTON 

UANSEL FOR DS40*UNPROT/ALPHA/SELPEN 

LOGICAL COMMAND CHARACTER DEFINITIONS FOR DS40 
WRITE] FGR ODS4O0=#HOME CURSOR ONLY (ESCH) 
ERASWRIT FOR DS40*ESC,yR*®HOME CURSOR»,CLEAR SCREEN 


LOGICAL CONTROL CHARACTER DEFINITIONS FOR DS40 


LOGICAL ATTRIBUTE BYTE DEFINITIONS FOR 1BM3270P 


LOGICAL COMMAND CHARACTER DEFINITIONS FOR IBM3270P 


LOGICAL COATROL CHARACTER DEFINITIONS FOR I8M3270P 


EQU 51 
EQU 52 
EQU 53 
EQU 54 
DC C'END OF WORKING STORAGE® 


Figure 48. Sample Reentrant Subsystem (Assembler) (Page 10 of 15) 
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1512 LTORG 

"1513 eV(PMIRTLR) 

1514 *eV(DYNLLOAC) 

1515 =CL15'"NO CC FCR FILE* 

1516 =CL15°IO ERROR CN* 

1517 INMSG DSECT 

1518 COPY *SGHDRC MESSAGE HEADER DSECT 

1519 * 

1520 * MESSAGE HEADER LAYCUT 

1521 * AERREAEEESEE EEE EEE ESD 

1522 * LAST REVISION 10/20/82-RELEASE 9.C 

1523 * LAST REVISION 07/30/85=-LU 6.2 SUPPORT 

1524 * 

1525 MSCFLEN OS BL2 LENGTH OF MESSAGE 

1£26 MSGFQPR OS BL1 CTAM/BTAM I/0 PREFIX BLANK ITF SS MSG 

1527 MSGFRSTH DS xL1 HI-ORDER BYTE OF RECEIVING SUBSYSTEM CODE 

1528 MSEFRSC DS CL1 RECEIVING SUBSYSTEM CODE 

1529 MSGHSSC PDS CL1 SENDING SUBSYSTEM CODE 

1530 MSGHMMN O05 OBL3 MONITOR SEQUENCE NUMBER X1078 

1531 MSGFETXTL DS BL2 RECORD LENGTH (FILE RECOVERY) xX1078 

1532 MSGRKEYL DS Cll KEY LENGTH (FILE RECOVERY) X1078 

1533 MSGHDAT DS OCL6 CATE (YY.CDO) X1078 

1£34 MSCFYR DS CL2 YEAR X1078 

1535 MSGFTHRD DS BL1 THREAD NUMBER X1078 

1536 MSGHDAY OS CL3 DAY X1078 

1537 MSGHTIM OS CL8 TIME (HR eMMeSS) 

1538 ORG MSGHTIM FIELOS USED IN SCANVERB DURING JA 

1539 *# CONSTRUCTION CF MESSAGE IN LINE HANDLERS JA 

1540 MSGFVFLG DS B FLAGS JA 

1541 MSGHVFND EQU x'so? VERB WAS ANALYZED BEFORE CALLING BTSEARCH JA 

1542 MSGHVBA ODS AL3 A(BTVERB ENTRY) IF MSGHVFND FLAG ON JA 

1543 ORG MSGHTIM+L*MSGHTIM JA 

1544 MSGEFTID ODS CL5 TERMINAL ID (AAANN) AAASCITYsNN#®DEVICE ID 

1545 MSGHMRDX OS OX INDEX TO MULTIREGION MCT ENTRY 

1546 MSGKCON ODS BLé COMPANY NUMBER 

1547 * SPECIAL VALUES CF MSGFCON JA 

1548 MSGFCFLA EQU X*BBO1' FLUSF-ALL CFASER MSG JA 

1549 MSCFCP12 EQU X"BBO3° 32270 COPY FORM 1 (REM.=SAME CU)e2 (3275-WR) JA 

1550 * PFSGHCP12: COPY TYPE 1 OR 2s ISSUING TERP REQUEST RESPONSE SM1124 

1651 MSGFCN12 EQU X*°BB13* COPY TYPE 1 GR 2, NC RESPONSE TO ISSUER S$M1124 

1552 MSCFCP3 EQU X'BBO2! 3270 COPY FORM3 (READ FULL BUF REQUEST) JA 

1553 MSGHR12S ECU x*aB04' I9M129 CARD READER RESET I/P INKIBITED MSG JA 

1554 MSGRFFEVR ECU X"*BB! SET IN MSGHCON+1 OF RESPCNSES TO F.E.VERBS JA 

1555 ORG MSGHCON+41 

1556 MSGHKRETN DS BL1 RETURN CODE. 

1557 MSGRCONV EQU c'c* 30 LOGGED FROM CONVERSE. 

1§58 MSGHFLGS DS OFL2 RESSACE INDICATOR FLAGS $¥1166 

1559 MSCFFLG1 DS FL2 MESSAGE INDICATOR FLAG-BYTE-1 541166 

1560 MSGHFSDR ECU x* eo? ASK FOR DEFIAITE RESPONSE VTAM 

1561 MSGFFSER EQU x*4Q' ASK FOR EXCEPTION RESPONSE VTAM 

1562 * IF MSGHFSOR+MSGHFSER#0Q THEN NC RESPONSE VIAN 

1563 * SPECIFICATIONs USE QTHER SOURCES TO DETERMINE. VTAM 

1564 MSGHFRSP ECU MSGHFSDR*#MSGHFSER MASK TO CHECK ‘SRESP* VTAM 

1565 MSGRFSR1 ECU x*20! 1 => RESPONSE TYPE 1 (FFE) VTAM 

1566 MSGHFSR2 EQU x*10' 1 => RESPONSE TYPE 2 (RRN) VTAM 
Figure 48. Sample Reentrant Subsystem (Assembler) (Page 11 of 15) 
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1567 MSGFFSEB 
1568 MSGENCON 
1569 MSGHFNF3 
1570 MSGHFRLS 
1571 * 
1572 MSCFFLG2 
1573 MSGHFETRM 
1574 MSGHSRST 
1575 MSGESYSC 
1576 * 
1577 MSGHFMHI 
1578 * 
1579 MSCFBMN 
1560 * 
1581 MSGRPMN 
1582 MSGHSSCH 
|} 1583 MSGHUSR 
1584 
1585 MSCFACDR 
1586 
1567 MSGHBKID 
1568 MSGEDD 
1589 MSCRLOG 
1590 RVZCNE 
1591 RCZONE 
1592 BSGFXFIL 
1593 RCSTUP 
1594 MSGHRQST 
1595 MSGHROND 
1596 MSGERBUF 
1597 MSGRMACR 
1598 MSGHBLK 
1£99 MSGEVMI 
1€00 MSGFFFVR 
1601 DOCVMI 
1602 * 
1€03 MSGHEND 
1604 MSGFLATH 
1605 * 


Figure 48. 


XL1 

XL1 
MSGHUSR 
AL3 
MSGHTID 
CL& 

CL& 

C*o! 
x'so!? 
x*90! 
RVZONE*15 
RCZONE+15 


Sample Processing Programs 


SEND EB WITH THIS MESSAGE VTAM 
DO NOT CANCEL CONVERSATION TIMEOUT XMO215 
1 => DONT WRITE X'F3"' LCG RECORD FOR MSG 
RELEASE NEXT CUTPUT MESSAGE $1166 
$M1166 
MESSACE INDICATOR FLAG-BYTE=2 SM1166 
MSGHADDR PCINTS TO SOURCE BTERM/LUC SM1166 
SERIALLY RESTARTED MESSAGE INDICATOR (9.0) CH 
CUEUE THIS MSG TO A 642 SESSION EVEN 51D 
IF NO CONVERSATION CURRENTLY ACTIVE 5160 
THIS MESSAGE CONTAINS 622 FMHDR 


BTAW SEQUENCE NUMBER 


HI/ORDER BYTE OF SENDING SUBSYSTEM 
AVAILABLE TO USER 


ADDRESS OF AN AUXILIARY AREA (FE ONLY) 
FOR FILE RECOVERY 
BDAM BLOCK ID (FILE RECCVERY) 
FILE DDNAME (FILE RECOVERY) 
LOG TYPE CODE -SEE MONITOR WRITEUP 
FILE REVERSAL ENTRY. 
FILE RECREATION ENTRY 
CHECKPOINT RECORD. 
STARTUP RECORD. 
LOGPRCC REQUEVEING STARTED. 
LOGPROC REQUEUEING ENDED. 
BUFFER LENGTH (BDAM FILE RECOVERY) 
FILE FANDLER MACRO # 
BLANK (BINARY ZERO) 
VERB/MSG IC 
SPECIAL VMI FOR FULLY FORMATTED MSGS 
SPECIAL VMI FCR DYN. DATA QUEING 


MSGHEND=MSGHLEN LENGTH OF MESSAGE HEADER 


Sample Reentrant Subsystem (Assembler) (Page 12 of 15) 
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1607 WORKAREA DSECT 
1608 SAVE os 
1609 CALLIST OS 
1610 DWCROD OS 
1611 * 
1612 ECB DS 
1613 #* 
1614 ADDRMSG OS 
1615 OMSGHTIO OS 
1616 RECAREA ODS 
1€17 PARTREC OS 
L618 PARTDATA DS 
1619 RECPIN DS 
1620 RECDES DS 
1621 RECLNT DS 
1622 RECPRC DS 
1623 RECMFR# ODS 
1624 DS 
1625 STCCKREC DS 
1626 DELECHR ODS 
1627 KEYFLD DS 
1628 RECWHS DS 
1629 RECPNO DS 
1€30 DS 
1631 RECSTKDT DS 
1632 RECwWLC DS 
1633 RECLEV DS 
1634 RECLOT DS 
1635 RECCRD DS 
1636 RECCOT DS 
1637? STATWC DS 
1638 FFSTAT DS 
1639 FHSTAT1 ODS 
1640 FHSTAT2 ODS 
1641 DS 
1642 EXTDSCT OS 
1643 RBNKORD ODS 
1644 DS 
1645 RBNWRCE DS 
1646 CURRFILE DS 
1647 MCh DS 
1648 MCWRETCD OS 
1649 MCWOPT2 OS 
1€50 MCWOPT3 OS 
1651 MCWOPT4 OS 
1652 ORG 
1653 MCkCD12 ODS 
1654 ORG 
1655 MCB DS 
1656 KEYFIELD DS 


Figure 48. 
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CL5 
OCL100 
OCL100 
OCL64 
CL5 
CL54 
CL5 
PL4 
CLi5 
CL17 
OCL80 
Xx 
OCL8 
XL3 
XL5 
XL28 
OCL43 
XL23 
PL4 
XL6 
PL4 
XL6 
OF 

OF 
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1658 
1659 
1660 
1661 
1€62 
1€63 
1664 
1€65 
1€66 
1667 
1668 
1€695 
1€70 
lé71 
1672 
1€73 
1674 
1675 
1€76 
1¢7? 
1¢76 
1679 
1680 
1681 
1682 
1683 
1684 
1685 
1686 
1€87 
1€86 
1€89 
1690 
1€91 
1€92 
1693 
1694 
1695 
1€96 
1697 
1698 
1699 
1700 
1701 
1702 
1703 
1704 
1705 
1706 
1707 
1708 


Figure 48. 


DATEDIT 
DEMC 
DEDAY 

DE YEAR 
DATEMOVE 
DMMO 
SLASH2 
DMDAY 
SLASH1 
DMYEAR 
INVINMSG 
MSG? 


NOPRTMSG 
MSG] 
NOPART 
MSG2 


NOWARPSG 
MSG3 
NOWARENO 
¥SC4 
NOWARKHS 


CANFSG 
CANCODE 
CANFLNM 
MSG5 


MAPERBSE 
MSG6 
ERRTAG 


NCSUBMSG 
MSG8 
NOGFILE 
MSG9 


ITOGRP 
ERMAP 
IOMAP 
SUBNAME 
MAPFLG 
MAPERR 
NOMAP 
FHFLAG 
BORCOK 
VSRCDOK 
ICERR 
OUTMAP 
WORKLEN 


0S OCL6 

DS CL2 

OS CL2 

DS Cle 

DS OCL8 

DS CL2 

DS X 

DS CL2 

OS X 

DS CL2 

DS OCL50 

DS CL50 

ORG INVINMSG 
OS OCL28 

DS CL12 

DS CL5 

DS CLll 

ORG INVINMSG 
DS OCL37 

DS CL5 

DS CL5 

DS CL24 

DS CL3 

CRG INVINMSG 
DS OCL43 

DS CLi5 

DS CL8 

DS CL20 

ORG INVINMSG 
DS OCL19 

DS CL1? 

DS ClL2 


ORG INVINMSG 


Sample Processing Programs 


DS OCL(L*MSG8+L*NOFILE+L'MSG9) 


OS CL(L'MSGJ) 
DS CL8 
DS CL(L*MSGK) 


DS CL8 
DS CL8 
0S CL8 
DS CL8 
DS X 

EQU Xx'40!' 
EQU x*'O1' 
CS X 

ECU x* eo! 
ECU x'ost 
EQU X'02! 
DS OD 


MAP GROUP NAME 
ERROR MAP NAME 
MAP NAME 
SUBROUTINE NAME 


ERROR MAP BEING SENT 
UNABLE TO SEND MAP 


BDAM READ SUCCESSFUL 
VSAM READ SUCCESSFUL 


I/O 


ERROR OCCURRED 


Sample Reentrant Subsystem (Assembler) (Page 14 of 15) 
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1710 
17il 
1712 
1713 
1714 
1715 
1716 
1717 
1718 
1719 
1720 
1721 
1722 
1723 
1724 
1725 
1726 
1727 
172 
1729 
1730 
1731 
1732 
1733 
1734 
1735 
1736 
1737 
173€ 
1739 
1740 
1741 
1742 
1743 
1744 
1745 
1746 
1747 
1748 
1749 
1750 
1751 
1752 
1753 
1754 
1755 
1756 
1757 
1758 
1759 
1760 


Figure 48. 


STKSTAT 
MAP 
VERBL 
VERGT 
VERB 
PARTNGF 
PARTNOL 
PARTNOT 
PARTNO 
FILLER 
RBNBYTE 
USEG1 
hKESNOL 
WESNOT 
WrSNO 
PRTDATAL 
PRIDATAT 
PRTCATA 
ORDUNTL 
ORDUNTT 
ORDUNT 
PRTPRCL 
PRTPRCT 
PRTPRC 
WHSLOCL 
WHSLOCT 
WHSLOC 
STKLEVL 
STKLEVT 
STKLEV 
LEVDATEL 
LEVCATET 
LEVCATE 
STKORDL 
STKORDT 
STKORC 
CROCATEL 
CRODATET 
ORDDATE 
MAPIL 


ERRMAP 
ERRMSGL 
ERRMSGT 
ERRMSG 
ERRMAPL 


STKSTATL 
DYNLEN 


Sample Processing Programs 


COPY STKSTATA SYMBOLIC 1/0 MAP DSECT 


DSECT 

EQU * START OF MAP 

DS XL2 FIELD LENGTH 
DS X FIELD TAG 

DS Ci4 

OS CXL3 STRUCTURED SEGMENT START 
DS XL2 STRUCTURED SEGMENT LENGTH 
DS x STRUCTURED SEGMENT TAG 
EQL * 

DS ZL4 

DS Z 

ECU * SEGMENT DELIMITER 
DS XL2 FIELO LENGTH 
DS x FIELD TAG 

DS ZL3 

DS XL2 FIELD LENGTH 
DS X FIELO TAG 

OS CL54 

DS XL2 FIELD LENGTH 
DS x FIELD TAG 

0S CL5 

DS XL2 FIELD LENGTH 
DS Xx FIELD TAG 

DS PL4 

DS XL2 FIELD LENGTH 
DS xX FIELD TAG 

DS CL23 

DS XL2 FIELD LENGTH 
DS x FIELD TAG 

DS PL4 

DS XL2 FIELD LENGTH 
DS X FIELD TAG 

DS CL8 

DS XLe FIELD LENGTH 
DS X FIELD TAG 

DS PL4 

DS XL2 FIELD LENGTH 
DS X FIELD TAG 

OS CL8 

ECU ¥=MAP1 SINGLE MAP LEAGTH 
CRG 

EQU * MAP 

DS XL2 FIELD LENGTH 
DS x FIELD TAG 

DS CL50 

EQU #—ERRMAP SINGLE MAP LENGTH 
ORG 

EQU #=STKSTAT MAP GROUP LENGTH 

ECU WORKLEN*STKSTATL 

END 
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~ 
oVayv ous Ww 


— 
No 


35 


SS REGISTER USAGE %% 

=x R93 WORK REGISTER ¥% 
x2 R4 WORK REGISTER ** 
2 R6 BAL REGISTER ¥* 
=x R11 PARM POINTER ** 
=% R12 BASE REGISTER ** 
*% R13 SAVE AREA om 


PRINT NOGEN 
SQASMB CSECT 
REGA REGISTER EQUATES 
SUBLINK LEN#WORKLEN,BASE#*(RC) »PARM2(RB) 


36¢*,SUBLINK = V9.0 = 08/82 


52¢ 
56+ 
174 


203 
204 
205 
206 
217 
218 
219 
229+ 
248+ 


PRINT NOGEN 


¥eGETSPA = V7.0 = 11/76 = SM 
USING WORKAREA,RD 
ex SELECT BDAM FILE 
MVC DDNAME »,DODPART MOVE DD NAME INTO WORK AREA 
CALL SELECT, (EXTOSCTsFHSTAT »DDNAME) VL yMF2(E sCALLIST) 
CLI FHSTAT1,C'°9° SELECT OK? 
BNE SELECTOK YES 
MV] RETCD#1l5912 NOeeRETURN CODE = 12 
B RETURN 
SELECTOK OS OH 
XC FHSTAT,FHSTAT CLEAR FH CONTROL WORD 
BAL R6&,READ GO READ A RECORD 
CLI FHSTAT1«C°1l" IOERROR? 
BNE NOT1 NO 
MVI RETCD+1+4 YESeeRETURN CODE = 4 
B DORLSE GO RELEASE THE FILE 
NOTI DS OH 
CLI FHSTAT1+C*%2°* RECORD NOT FOUND? 
BNE DORLSE FOUND, RETURN CODE = O 
MVI RETCO+1,58 NOT FOUND, RETURN CODE = 8 
DORLSE OS OH 
XC FHSTAT »FHSTAT CLEAR FH CONTROL WORD 


CALL RELEASE, (EXTOSCT »sFHSTAT) »pVLy»MFa(E,CALLIST) 
RETURN DS OH 
LH RFsRETCD LGAD RETURN CODE 
RTNLINK ADDR=(RD) »sLEN#WORKLEN,RC#(RFE ) 
PRINT NOGEN 
¥y9GETSPA = V7.0 = 11/76 = SM 


Figure 49. Sample Assembler Subroutine (Page 1 of 2) 
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READ OS 


Sample Processing Programs 


OH 


* REGISTER 11 CONTAINS PARM LIST FROM SQASMA 


L 

L 
CALL 
BR 


DDPART 


WORKAREA DSECT 


FHSTAT1 


EXTDSCT 
DDNAME 
CALLIST 
RETCD 
WORKLEN 


R3;0(RB) FIRST PARM *= ADDRESS OF RECORD AREA 
R4,4(RB) SECOND PARM = ADDRESS OF RBN 

READ s(EXTDSCT sFHSTATsO(R3)91(R4)) oVLgMFe(EsCALLIST) 

R6 RETURN 


CLE*PARTFILE ® 


=V(PMISUBL2) 
=sV(PMIRTLR) 


Figure 49. Sample Assembler Subroutine (Page 2 of 2) 
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Chapter 12 


SUBSYSTEM TESTING 


12.1 INTRODUCTION 


After a new subsystem has been thoroughly desk-checked and 
assembles cleanly, it becomes necessary to test the _ subsystem's 
execution under the control of Intercomm. Three methods of testing are 
available: 


e Simulated--batch execution of Intercomm with a simulated BIAM 
Front End. Message input streams are created via the 
CREATSIM utility program. Additionally, 3270 terminal input 
and output screen, or output printer, images are formatted if 
the SIM3270 utility is implemented for the simulation mode 
execution. Illustration of this mode of testing is provided 
in this Chapter, and is particularly useful for testing 
messages processed via the Message Mapping Utilities. 


e Test Mode--batch execution of a Back End Intercomm with 
message input from a card-image data set, as described in 
Chapter 13. 


e On-line Testing--an on-line system is necessary for final 
testing of all error conditions, multithread processing, etc. 
and can be either a single region system, or a satellite 
region used primarily for testing within a Multiregion 
production system. 


12.2 DEBUGGING APPLICATION PROGRAM PROBLEMS 


Text and descriptions of error messages issued by Intercomm as a 
result of invalid program logic paths, along with descriptions of 
general debugging techniques for accompanying snaps and abends are 
available in Message and Codes. Additional debugging facilities such 
as dispatcher trace reports, thread dumps and indicative dumps are 


described in the Operating Reference Manual. 
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12.3 TESTING A SUBSYSTEM WITH THE FRONT END SIMULATOR 


As described in the Operating Reference Manual, a test execution 


with a simulated Front End is very useful to determine Front End 
message interface problems that may be harder to debug when using an 
on-line test system. Although the simulation is of certain BTAM 
devices, including a local 3270, the access method interfaces required 
for a remote 3270 or a TCAM or VTAM Front End are essentially 
transparent to the application programmer as the interface dependent 
code is handled by Intercomm. 


This chapter illustrates testing of the subsystem and subroutine 
described in Chapter 11 using the BTAM simulator for 3270 CRT messages 
processed via maps defined for the Message Mapping Utilities. 


To test an application system in a simulated Intercomm 
environment, do the following: 


NOTE: Steps preceded by an asterisk (*) may often be performed 
for the application programmer by an installation's 
Intercomm System Manager. Appendix C summarizes the 
Intercomm Table entries. 


1. Compile and linkedit the user subsystem(s) and subroutine(s), 
if any. Appendix A describes Intercomm-supplied Assembler 
JCL procedures. 


*2. Create or add to a USRSCTS member on a user test library to 
contain a Subsystem Control Table Entry (SYCTTBL macro) which 
describes the subsysten. Reassemble and link INTSCT which 
copies the USRSCTS member from the test library (see Figure 
50). 


*3. Define input message verbs in the copy member USRBIVRB via 
BIVERB macros and reassemble and link the Front End Verb 
Table BIVRBTB (see Figure 50). 


*4,. Code a SUBMODS macro addition to the COPY member USRSUBS to 
define the Assembler subroutine and reassemble and linkedit 
REENTSBS which copies USRSUBS (see Figure 50). 


5. Assemble and linkedit MMU maps (Map Group STKSTAT--see Figure 
51) to the MMU load module library. Load maps to the 


appropriate Store/Fetch data set. See Message Mapping 
Utilities, 


6. Prepare input test message data set(s) using the CREATSIM 
utility as illustrated in Figure 52. Note that the first 
message generates, via the MMU command MMUC, the _ screen 
template to be used for entering an inquiry transaction. All 
‘subsequent input messages are for testing the Assembler 
subsystem and subroutine, including input error conditions 
handled by the application program. 
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*7. 


*8. 


*9, 


10. 


ll. 


*12. 


alts 


Add control cards to the linkedit deck for the user programs, 
unless the routines are dynamically loadable (see Figure 53). 


Add INCLUDE statements for the simulator (BTAMSIM) and 3270 
display formatter (SIM3270) to an Intercomm linkedit deck 
which was created for the BTAM Front End (see Figure 53). 


Linkedit to create a new Intercomm load module (see Figure 
53). 


Add DD statements to the Intercomm execution JCL for the 
printed SIM3270 output and the input message data set(s) (see 
Figure 53). 


Create test data sets and add DD statements for them to the 
execution JCL (see Figure 53). Note that if a VSAM data set 
is used with a user catalogue, place the STEPCAT DD statement 
after the //PMISTOP DD statement (see Figure 53); do not use 
a JOBCAT DD statement. Omit the STEPCAT statement if dn ICF 
catalogue is used. 


Execute in simulation mode: 


a. Single-thread test all subsystems; to test a reentrant 


subsystem, specify MNCL=1 in the subsystem’s SYCTTBL 
macro. 


b. Multithread test reentrant subsystems (change MNCL) using 
several test message input data sets or use a single data 
set as input from more than one terminal. 


The parameter ‘STARTUP’ must be coded on the Intercomm EXEC 
statement. Figure 53 illustrates a sample execution deck 
with test message input (DD statement TEST1) for the sample 
inquiry program and JCL to print the system log. 


The resulting SIM3270 printouts for the simulated execution 
of the sample inquiry subsystem are illustrated in Figure 


54. Note that the underlined positions on each screen 
display indicate attribute byte positions; codes are 
described under the display. On an actual terminal, the 


attribute byte position appears as a blank to the terminal 
operator. See Message Mapping Utilities and IBM 
documentation on programming for the 3270 CRT for further 
information on attribute codes. 


The Intercomm Log printed after the simulated execution of 
the sample inquiry subsystem is shown in Figure 55. 


Test the subsystem concurrently with other application 


subsystems. 


131 


Chapter 12 Subsystem Testing 


//TABLES 
DEFINE SYCTTBL FOR SUBSYTEM 


EXEC LIBELINK,Q=TEST ,NAME=INTSCT , LMOD=INTSCT 
//LIB.SYSIN DD * 
_/ ADD NAME=USRSCTS 
_/ NUMBER NEW1=100 , INCR=100 
USRSCTS DS OH 
RA SYCTTBL SUBH=R, SUBC=A, SBSP=SQASMA, LANG=RBAL, OVLY=0, 
NUMCL=10 , MNCL=2 , TCTV=60 


/* 
//ASM.SYSIN ODD DSN=INT.SYMREL(INTSCT) , DISP=SHR 


DEFINE BIVERB FOR SUBSYSTEM 


EXEC LIBELINK,Q=TEST,NAME=BTVRBTB , LMOD=BTVRBTB 
//LIB.SYSIN DD * 
_/ ADD NAME=USRBTVRB 
_/ NUMBER NEW1=100 , INCR=100 
USRBTVRB DS OH 
BTVERB VERB=MURA, SSCH=R , SSC=A, CONV=18000 
/* 
//ASM.SYSIN DD DSN=INT.SYMREL(BTVRBTB) ,DISP=SHR 


DEFINE SUBMODS FOR SUBROUTINE ) 


EXEC LIBELINK,Q=TEST ,NAME=REENTSBS , LMOD=REENTSBS 
//LIB.SYSIN DD ¥* 
./ ADD NAME=USRSUBS 
./ NUMBER NEW1=100 , INCR=100 
USRSUBS DS OH 
SUBMODS LNAME=SQASMB, TYPE=BAL, DELTIME=30 
/* 
//ASM.SYSIN DD  DSN=INT.SYMREL(REENTSBS) ,DISP=SHR 
// 


Figure 50. Table Updates to Implement Simulation Mode Testing 
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STKSTAT 


MAP 1 
VERB 


PARTNG 
FILLER 


RBNBYTE 


WHSNO 


PRTDATA 


OROUNT 


PRTPRC 


WHSLOC 


STKLEV 


LEVDATE 


STKORD 


ORDDATE 


ERRMAP 


892 


ERRMSG 


Subsystem Testing 


MAPGROUP MODE=1/0.DEVICE=1843270 


MAP 
FIELD 


FIELD RELPOS=(lse7),INITIAL=°ENTER TRANSACTION CODE*sATTRIB#PSN 


FIELD 
FIELD 


SIZE#(20,80) oSTART#(151) 
RELPOS=VERB 


RELPOS#(3923)eINITIALS"ENTER DATA? *sATTRIB2PSN 
RELPOS#(597)oINITIALS°PART NOs *,ATTRIB*PAHSEL 


SEGMENT 


FIELD 
FIELD 


REL POS=(5 416) sFORMAT=(459,720) sATTRIBSUNN 
RELPOS#(5520) »FORMAT#(1¢20) 


SEGMENT 


FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 


FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELO 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELO 
FIELD 
MAP 

FIELD 


ABOVE CLEARS STOCK STATUS INFO. WHEN ERROR MESSAGE APPEARS 


FIELD 
FIELD 
FIELD 


RELPOS#(5522)sFORMAT#1,ATTRIB=PSN 
RELPOS#(697)eINITIAL#°WHS NO? *,ATTRIB#*PAHSEL 
RELPOS#(6515) sFORMAT#(34,Z0),ATTRIB#UNN 
RELPOS#(69019) sFORMAT#1 ,ATTRIB2=PSN 

RELPOS=(8e23) eINITIAL#®°STOCK STATUS *,ATTRIB=PSN 
REL POS#(10,7),INITIAL=*DESCRIPTION: *,ATTRIB=PSN 
REL PGS=(10.20)5FORMAT #54, ATTRIBSUAN 
RELPOS#(109 76) eFORMAT#1 sATTRIB#PSN 
RELPOS#(1l1leo7),INITIAL#*"ORDER UNITS: *,ATTRIB=PSN 
RELPOS#(11,20) sFORMAT#5,ATTRIBSUAN 
RELPOS#(11+.26) sFORMAT#1,ATTRIB#®PSN 

RELPOS2(11 540) ¢INITIAL=*PRICE?*® sATTRIB#PSN 
RELPOS#(11947) sFORMAT#(95459%PD0S4) sATTRIB®SUAN 
RELPOS=(11,57) sFORMAT=l1eATTRIB=PSN 
RELPOS#(13523) INI TIAL#=*STOCK STATUS AT WAREHOUSE:', 
ATTRIB#=PSN 
RELPOS#(1597),INITIAL#*LOCATION: ® ,ATTRIB2PSN 
RELPOS2(15917) sFORMAT#23,ATTRIB2UAN 
RELPOS=(15541) sFORMAT#=1¢ATTRIB#PSN 
RELPOS#(l657)5INITIAL#°ON HAND: *,ATTRIB#PSN 
RELPOS2#(16916) sFORMAT#(754,PD) sATTRIB2UAN 
RELPOS2#(16924) sFORMAT#1,ATTRIB®PSN 
RELPOS#(16940) ¢INITIAL#°AS OF 3*,ATTRIB#PSN 
RELPOS=(16547) sFORMAT=8 sATTRIB#*UAN 
RELPOS=(16556) sFORMAT#1LsATTRIB#PSN 
RELPOS#(17,7)eINITIAL#="ON ORDER: * sATTRIB#PSN 
RELPOS=(17517) »sFORMAT#(754,5P0) sATTRIB2UAN 
RELPOS=(17525) sFORMAT#1 ,ATTRIB2PSN 
RELPOS#(17s40),INITIAL#°AS OFS *,ATTRIB#PSN 

REL POS#(17247) sFORMAT=8,ATTRIB=#UAN 
RELPOS=(17556)sFORMAT#1,ATTRIB#=PSN 

SIZE#(15380) sSTART#(1091) 

RELPOS2(1,1) sATTRIBSSUPR,INITIAL #X°125B5F ° 

oes 
RELPOS2(14,33) INI TIAL@*ERROR MESSAGES * psATTRIB*PAHSEL 
RELPOS#(15910) sFORMAT#50,ATTRIBSUAHSEL 
RELPOS=(15461) sFORMAT#1,ATTRIB#=PSN 


ENDGROUP 


END 


Figure 51. 


MMU Maps Used by Sample Subsystem 
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00000010 
00000020 
00000030 
00000040 
00000050 
00000060 
00000065 
00000070 
00000075 
00000077 
00000080 
00000090 
00000100 
00000110 
00000120 
00000130 
00000140 
00000150 
00000160 
00000170 
00000180 
00000190 
00000200 
00000210 


X00000220 


00000230 
00000240 
00000250 
00000260 
00000270 
00000280 
00000290 
00000300 
00000310 
00000320 
00000330 
00000340 
00000350 
00000360 
000003 70 
00000380 
00000390 
00000400 
00000410 
00000420 
00000430 
00000440 
00000450 
00000460 
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//CREATSIM JOB 

//CRS PROC Ts 

//* SCRATCH OLO TEST INPUT DATA SET CIF ARY) 

4/8 EXEC PGM=#IJEFBR1I4 

//SCR DD ODSNFINT.TET,DISP#(OLD,OELETE) 

J/CRS EXEC PGMSCREATSI® 

//* CREATE NEW TEST INPUT DATA STREAM FOR 3270 DEVICE 

//STEPLIB DO OSN#INT.MCOLIB,DISP HSER 

// DO OSN#INT.MODREL »DISP#SkR 

//SYSPRINT DD SYSOUT#A 

J/SYSUT2 DD DSN#@INT.TET »DISP=( ,CATLGsCATLG) »sUNI T#ONLINE, 

// VOLeSER@#INTOO1] »SPACE=(TRKo(191)) 

//OUMP EXEC PGM#IEBPTPCH 

//* PRINT MESSAGES GENERATED ON TEST INPUT DAT SET 

//SYSPRINT OD SYSOUT#A 

J/SYSUTI1 CO OSN#*,.CRS.SYSUT2,DISP20LD 

L/SYSUT2 CC SYSOUT#A 

// PEND 

//*  FCR THIS EXECUTION OF CREATSIM,y THE ENC-OF-CARD CHARACTER IS A 
//* SEMI=-CCLON, (USE ALSO AFTER THE VERB-FRONT END SEES THE SBA)» 
//* THE PESS4GE END CHARACTER IS AN EXCLAMATION POINT (E0B?). 
//EXECCRS EXEC CRS»T#TESTIL 
//CRS.~SYSIN ODD # 
GRAPHEIC,ADD» 5 FF 
GRAPHIC,ADD,<7C 

SBA M2 

€ MMUC,SHCWKe(STKSTATsMAPL) 
q€ 5 
SBA,C1C25 

MURA; 

SBA,C516;5 

12345; 

SBA,C6153 

200 

ae 

$8A,0102; 

MLRA; 

SBA,C516;5 

§5555; 

SBA,C615; 

200 

<q 3 

SBAsC102; 

MURA; 

SBA,C516; 

12348; 

SBA,C615; 

3¢C0 

< 3 

SBA,C102;3 ; 7 
MURA; 

$BA,0516; 

12341; 

SBA ,C6153 

600 

< 3 

§$BA,C102; 


CONTINUATION CODE 
ENTER KEY 
USING MODEL 2 SCREEN SIZE 


Figure 52. 
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00000100 
00000200 
00000300 
0¢€C00400 
00000500 
00000600 
00000700 


“00000800 


00C00S00 
00001000 
00001100 
0¢c001200 
00001300 
00001400 
00001500 
00001600 
00C01700 
00001800 
00C€01900 
00002C00 
00002100 
00002200 
00002300 
00002400 
00002500 
00002600 
00002700 
00002800 
00C02900 
000030C0 
00003100 
00003200 
00003300 
0CC03400 
00003500 
00003600 
000037C0 
0C003800 
00003900 
00004000 
00004100 
000042C0 
00004300 
CC004400 
C0C04500 
00C04é4C0 
00004700 
00004800 
C0004900 
00C05000 
00005100 
00005200 
00005300 
0C005400 
00005500 
00C05600 
000C5700 
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MURAS 
SBA,C5165 
A2345; 
SBA,TE153 
200 


SBA»C1025 
MURA; 
SBA,C516;3 
123455 
SBA,C615; 
BCO 


$BA,C102; 
MURAS$ 
$BA,05163 
1234X; 
S$BA,C615;5 


20Y 

< 3 
SBA,01023 
MURA; 
S$BA,C516;5 
123439; 
$BA,C615; 
100 

< 3 
S$BA,0102;3 
MURA3 
SBA,C5165 
12342; 
SBA,061L55 
1C0 


//DUMP.SYSIN DOD * 
PRINT TYPORG#=PS sTOTCONV=XE ,CNTRL22 


ff 


Figure 52. 
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00005800 
00005900 
00C06000 
000C6100 
00006200 
00006300 
00006400 
00006500 
00006600 
00006700 
00006800 
00006900 
00007000 
00c07100 
00007200 
00007300 
0000740C 
00007500 
occd7600 
00C07700 
000076800 
00007900 
00008000 
co0006100 
00008200 
00008300 
00008400 
00008500 
00008600 
00008700 
00008600 
000089C0 
00009000 
00009100 
00009200 
00C09300 
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//EXECTEST JOB CICCMTESTs9920)5°SQASMA TEST*sCLASS=A,y 
// RESTART#(GENLINK. ASP) 


//PRCCLIB 


DD DSN#®IANTePROCLIB»DISP#SHR (AS NEEDED) . 


Jf/SSHSPHSHHEHAKKHKEKEEKEEDEEEEEEEEESEEEEEEEEEEEEEEEEEESEHEEEEEEHEERESSEHEDES 


//* TRE RESTART PARM IN TRE JOB STATEMENT RESTARTS THE TEST AT THE 
//* BEGIANING. IF YCU WISH TO RESTART AT A SIFFERENT STEP, CODE 
//* RESTART®STEPNAME OR RESTART#®STEPNAME. PROCS TEPNAME 


//* 
//* NCTE? 
//* 


J f/SSSSESHSESSEKKEKE HS HEKEEEEEEEEEEEEEEEEEEHEOOEEEEEHEEEHESESEERSEEEEESE HESS 


//* 


WHEN USING A VSAM FILE, IT IS NECESSARY TO EXECUTE IOCAMS 
TO VERIFY THE FILE IF A PREVIOUS EXECUTION ABENDED. 


* 
+ 
s 
* 
S 
* 
* 


[PEO OR EERE EEE TORE EEE E ERSTE EEE EEE ES EEEOEE HEHEHE EE ESOEEEEETE HEED EES S 
//* STEP GENLINK GENERATES A STANDARD BTAM FRONT END LINKEDIT OECK 
//* VIA ASSEMSLY OF THE ICOMLINK MACRC. IF ONLY A VTAM FRONT END IS 


//* USED, 


A SETGLOBE WITH THE BTAM GLOBAL SET ON MUST BE IN THE 


//* LIBRARY SPECIFIED BY THE Q= PARM. ADD OR CHANGE PARMS FOR THE 
//* ICOMLINK MACRO BASED ON INTERCOMM FACILITIES USED. 
//* TRE GENERATED DECK (SIMLINK) IS PLACED ON INT-SYMTEST. * 


//* NOTE: 
//* 


THE SPECIFIED FRONT END NETWORK TABLE (FENETWRK) CONTAINS A 
DEFINITION FOR THE TEST TERMINAL TESTI AS A LOCAL BTAM 3270. 


J /SSASSSSSESESS HES ESET EKER EEEEEEEHEEEEEESEEHEEEEEEEEHEEEEESEEEEH HEHEHE 


//GEKLINK 


EXEC ASMPC,Q=TESTs»DECK*#DECK 


J/ASM.SYSIN DD * 
ICCMLINK MMU#YES ,FETABLE=FERETWRK 
END 


/* 


J/SYSPUNCH DD DSN#®INTSSYMTEST(SIMLINK) »DISP#SHR 


//* 


J /RROEREEEE EH SEE EE EEE EERE EEE EERE EEEREEE EEE EEEEE EEE EEEEEHEEEE ERE TE EEE 
//* STEPS SCRSCR AND ALLOCSCR DELETE AND RE-ALLOCATE THE LOAD * 


//* MODULE LIBRARY USEC IN THE TEST (ALSO USED FOR DOYNLLIB) * 
Jf POREEHH EERE RAREST EEED EEE EEEEEEEEEEEEEEEEEEEE SES EEEEEEE EEE EEEEEESEDE 


//SCRSCR 
//FILEL 
J/ALLOCSCR 
//A 


EXEC PGM=IEFBR14 

DD DSN#*INT.MODSCRsDISP#(GLDsDELETE) 

EXEC PCM=IEFBR14 

DO DSN=INT.MODSCR»DISP#( pCATLG) sUNIT#SYSDA, 


// OCB=INT.MODLIBsVOL=SERSINTOOL»SPACE= (CYL s(3997) 


Figure 53. 
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[/PETOHHS SEAS EE SEES EEH EEE SHE RET EE SESE DE SREEERESHEREEEEEREEEEEEEES 
//* STEP GENINCL CREATES INCLUDE CECK USED BY TKE LINK EDIT STEP: * 
//* THE ADDED INCLUDE STATEMENTS ARE FOR THE SAMPLE SUBSYSTEM ANC * 
//* THE REQUIRED SIMULATION MCOE MODULES. * 
//* IF THE TEST1L TERMINAL IS NOT IA THE SYSTEM PMISTATB TABLE, ACD: * 
//* INCLUDE MODREL(PMISTATB) * 
//* INCLUDE MODREL(PMIDEVTB) 2 
//* INCLUCE MODREL(PMIBRCAD) * 
//* THE ABOVE ASSUMES THE CONTRCL TERFINAL IS NAMED CNTOl1. * 
J JRE OREO RERAEEEER EERE EERE EEEEEEE SEES EES EEE EEEEREEEEEROEERE SEEDS EES 
//GENINCL EXEC PCM#IESUPOTE 
//SYSPRINT OO SYSOUT#A 
J/SYSUT1 C0 DSN#INTeSYMTESTsDISP=SHR 
//SYSLT2 OD DSN=EEINCL ys DISP=( yPASS) oLNIT#SYSDAySPACESICYL» Clolyl) dD» 
4/ DCB=(BLKSIZE#80,LRECL#@0) 
/S/SYSIN DO * 
eo/ CRANGE NAMESSIMLINK,LIST#ALL 
INCLUDE SYSLIB(SQASMA) ccco0010 
INCLUCE SYSLIB(BTAMSIM) 00000020 
INCLUDE SYSLIB(SIM3270) 00000030 
/* 
J /ERREEREEREEEEESEEREREEERETESEEEE EEE OEEEEEEEEEHEREEEREESEEEE SESE EETES 
//* LINK EOIT THE TEST INTERCCMM SYSTEM * 
//* NOTE TKAT THE INTERCOMM LKEOT PROC PLACES THE QUTPUT ON THE * 
//* MOOSCR LOAD LIBRARY CREATED ABOVE. * 
//* IT 1S NOT NECESSARY TO RE=D0 THE WHOLE LINK TO REPLACE 1 MODLLE * 
//* IN TRIS CASE, ALL YCUL SHOULD ODO IS: * 
//* 1) REASSEMBLE OR RECOMPILE THE CHANGED/NEh MOOULE INTO A * 
//* SEPARATE LOAD LIBRARY * 
//* 2) OVERRIDE THE SYSLIN OD STMT TO //LKEDeSYSLIN OD * * 
//* FOLLOW IT WITH INCLUDE CARDS * 
//* FOR THE MODULES YOU WISH TC REPLACE * 
//* 3) FOLLOW THOSE INCLUDES WITH THE FCLLOWIAG 3 CARDS: + 
//* INCLUDE SYSLMOO(SIMICCM) * 
//* ENTRY PYISTUP * 
//* NAME SIMICCM(R) * 
//* 4) INSERT A DO STMT FOR THE LOAD LIBRARY ON WHICH THE * 
//* REPLACEMENT MOOULES RESIDE * 
//* 5) CHANGE THE RESTART PARM ON THE JOB STATEMENT * 
//* TO POINT TO THE LKED STEP. * 
[J f(PROREEE EEE EOE EEE EOEEE EEE EE EEE EE EEEEE EEE HOES HEEOEEEEEEEE EEE ES 
//LKED EXEC LKEDT,Q*TEST»LMOD2SIPICOM, 
// PARM.LKED#®*LISTsLETsXREFoNCAL»s SIZE#(250K,100K) € 
//LKEDeSYSLIN DD DSN#EEINCLOISIMLINK) sDISP#(OLO>,PASS) 
//MOCREL BO DOSN#® INT. MODREL »DISP#=SHR 
J /PRREROREREEEEHE ESET EEE EREHEE EERE EE EEE EEE EERE EEE EEEEEREEEEE EES 
//* LINKEDIT THE DYNAMICALLY LOADED SUBROUTINE * 
J /PPOEHRHRREREAEE EEE EEE EEEEEEES SO OOO4 EOE EEE EEE EEEEEEEESEEEESE EE EES 
//LIKKSQB EXEC LKEDT,Q=TEST,LMOD#SQASMB 
//SYSLIN 0D * 
IACLUDE SYSLIB(SCASMB) 
/* 


Figure 53. Linkedit and Execution JCL for Simulation Mode (Page 2 of 3) 
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J (PSHE SAEK SES EERE HEHEHE EHHEECAESEE HEHEHE EERE REEEEEHEEEEREREEES 
//* EXECLTE INTERCOMM IN SIMULATION MODE * 
J /RASHKEEHEEHESEE SEEKERS EEESEEEEEE EER OE SEES OEEEEEDREEDEEEOEEREEOREREDS 
4/60 EXEC PGM=SIMICOM,PARM='"STARTUP*,TIME=( 430) 

J/STEPLIS ODOC DOSN#INT.“ODSCR»DISP#SHR 

4/ OSN# INT .MOCUSR  ,DISP#SHR 

41 DSN#*INTe-MODLIB,DISP=SHR 

4/ DSN*INT.MODREL»DISP=SHR 

//TNTERLOG COD OSN#EEINTLOGoDISP=(NEW,PASS), 

J/ = =CCB#{DSORG#PS ,RECFM@VByBLKSIZE=4C96 sLRECL #4062 »yNCP=8,0PTCD#C}, 

// = =SPACEsS{TRK4(1055)),VOL#SER#®INTOOL,UNIT#=SYSDA 

//SMLCG DD SYSOLT#A,0CB#(DSORG=PS ,BLKSIZE#120 »RECFMBFA) 

//STSLOG CO SYSOUT#A,0CB#(OSORG=PS§ »,BLKSIZE#120 »RECFM=F A) 

J/SYSPRINT DO SYSOQUT#A,CCB2(DSORG#=PS »sBLKSIZE2142 »LRECL#137,RECFM#VA) 
//RCTOOO DD OSN=INT.~RCTOOC,DCB#(DSORG#DA,OPTCOSERF) sDILSP=SHR 
//PMICUE DD DSN#®INT.PPIQUE,OCB=(DSORG=DA,OPTCD#R) »-OISP=0LO 

7/BTAMQ DD OSN#INT.BTAMQ,DCBs(DSCRG#DA,CPTCO#R),DISP#SHR 
//INTSTORO OD OSN#INTSTCRO,DCB=(DSORG#DA ,OPTCD=@EF »LIMCT#3) »,DISP2CLD 
/J/INTSTCR2Z OD OSNZINTSTCR2Z2,D0CB=(DSCRG#=DA OP TCO@EF »sLIMCT=3) sDISP#SHR 
/J/INTSTOR3 DD ODSN#®INTSTOR3SsOCB#(DSORGSDA,0PTCO=EF sLIMCT#3) sO ISP=SHR 
//* TEST DATA SETS FOR SAMPLE SUBSYSTEM 

//STCKFILE OD OSN#VSAMSD1L.STCKFILE-CLUSTER,DISP=OLD, 

4/ AMP=(AMORG, *RECFM2F ® ) 

//PARTFILE DD OSN#INT.TESTePARTFILEsDISP=CLD, 

4/ DCBs(DSORG#CA,CPTCC#R) 

//* DATA SETS FOR SIMULATED TERMINAL == TEST1 

//TEST1 DO OSN#INT.TEST1»DOCB=D0SCRG#=PS,DISP=#OLD 

//SCRTEST1 DD SYSCUT#A,CCB2(DSORG=PS ,RECFMSFA,BLKSIZE#121) 

//SIMCARDS O00 * 

TEST1,001 

//PMISTOP DD OUMMY 

//* FAR PARAMETERS 

//TCCMIN DD * 

INTSTORO,sICCMBCAMXCTRL 

/* 

//SNAPDD DD SYSOUT#A 

//SYSUDUMP CO SYSOUT#A 

//STEPCAT OD OSN#®VSAMSC1,DISP#SHR 

//* DYNAMIC LINKEDIT DATA SETS 

//OYNLLIB DD DSN#INT.MODSCR,DISP#SHR 

//DYNLPRNT DD SYSOQUT#A 

J/DYALHKORK DD UNIT#SYSDA,SPACE#(CYLo(1l91)),D01SP2#( PASS) 

J (PREAH EERE EEE EEE EREKEE EERE RE ERE EE ERHEE SERENE REHEREREEEEEEREEES 
//* PRINT TRE INTERCOMM LOG GENERATED BY THE TEST * 
[Jf PEPOREC CEH AEEHE HER HERE SHREK ES ERO EEEEREEEEEEEEEEEEEEERECEE SEEDS 040888 
//INTERLOG EXEC PCGMsLOGPRINT +s COND#EVEN 

//STEPLIB OC DSN INT-MODREL »DISP#SHR 

/J/SYSPRIAT OD SYSOULT#A4,D0CB#(D0SORG#PS,BLKSIZE#121) 

//INTERLOG OD DSN*EEINTLOG,DISP#OLD,DCB#BLKSIZE2#5000 

JISYSIN DO DUMMY 

// 
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SUBSYSTEM TESTING IN TEST MODE 


13.1 INTRODUCTION 


All of the testing functions may be performed using the Intercomm 
Test Mode of operation without a Front End defined. Rather than 
receiving messages from a terminal, the Test Monitor reads messages 
into the system from a card-image data set. Snaps of input (snap 
id=15) and output (snap id=20) messages constitute a history of Test 
Mode execution. Essentially, the Front End is replaced by the Test 
Monitor (PMITEST) to drive the Back End as usual. In this way, 
subsystem testing can be going on in one or more regions or address 
spaces without affecting the on-line system. Figure 56 illustrates a 
sample reentrant Assembler subsystem (SQASM) designed for the same 
purpose as SQASMA, but using the Edit, Output and Change/Display 
Utilities. 


13.2 TESTING A SUBSYSTEM IN TEST MODE 


To add and test an application subsystem in Test Mode, do the 
following: 


NOTE: Steps preceded by an asterisk (*) may often be performed 
for the application programmer by an installation’s 
Intercomm System Manager. Appendix C summarizes the 
Intercomm Table entries. 


1. Compile and linkedit the application program. Appendix A 
describes Intercomm-supplied Assembler JCL procedures. 


*2. Create or add to a USRSCTS member on a user test library to 
contain a Subsystem Control Table Entry (SYCTTBL macro) which 
describe the subsystem. Reassemble and link INTSCT which 
copies the USRSCTS member from the test library (see Figure 
D7) 


*3. Create or add to a USRVERBS member on the user test library 
to contain an Edit Control Table (VERBTBL) entry for editing 
of input test messages by the Edit Utility. Reassemble and 
link PMIVERBS which copies the USRVERBS member from the test 
library (see Figure 57). 


*4. If a Fixed Format output message (VMI=X'72’) is created for 
processing by the Change/Display Utility, code an entry for 
the CHNGTB (see Figure 57) to define the DESOOO data set 
entry number for the File Description Record (DESO0001--see 
Figure 58). The PMIEXLD utility must be used to load the FDR 
to the DESOOO file (see the Utilities Users Guide and the 
Operating Reference Manual). 
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*7. 


*8. 


10. 


Subsystem Testing in Test Mode 


Code, assemble and link and add an INCLUDE statement for the 
OFT load module RPTnnnnn (RPTOO100 and RPTO0501--see Figure 
58) to the Output Format Table (PMIRCNTB) in the Test Mode 
Intercomm linkedit for output message formatting by the 
Output Utility. 


Prepare test messages via the SIMCRTA utility or as direct 
card-image input data (SYSIN data set). An input test 
message consists of a header card, detail cards, and a 
trailer card, grouped together as illustrated in Figure 60. 
Figure 59 details the required card formats. The message 
area in the Test Monitor will accomodate a message text up to 
958 bytes long. Longer messages would require a modification 
to the Test Monitor (PMITEST), as described in the Qperating 
Reference Manual. 


Add control cards to the linkedit deck for the user program, 
unless the subsystem is dynamically loadable (see Figure 61). 


Linkedit to create an Intercomm Test Mode load module (see 
Figure 61). 


Create test data sets and add DD statements for them to the 
execution JCL. 


Execute in Test Mode with test messages in card-image format: 


a. Single-thread test the subsystem; to test a reentrant 
subsystem, initially specify MNCL=l1 in the subsystem’s 
SYCTTBL macro. 


b. Multithread test a reentrant subsystem (change MNCL) 
using several test messages. 


Test Mode execution is activated by the parameter ‘TEST’ on 
the Intercomm EXEC statement. Figure 61 illustrates a sample 
execution deck with test message input (DD statement SYSIN) 
for the sample inquiry program and JCL to print the system 
log. 


The resulting snaps for the test mode execution of the sample 
inquiry subsystem are illustrated in Figure 62. 


The System Log printed after executing in Test Mode with the 
sample inquiry subsystem is shown in Figure 63. 


Test the subsystem concurrently with other application 
subsystems. 


‘to implement the sample subsystem for on-line execution, it 


would be necessary to code a BTVERB macro (in USRBTVRB--see 
Chapter 12) as follows: 


BTVERB VERB=RTRA, SSCH=R, SSCA, CONV=18000 , EDIT=YES 
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SQASM CSECT 


SAMPLE REENTRANT ASSEMBLER SUBSYSTEM USING ThE FILE HANDLER TO 
ACCESS BOAM AND VSAM FILES. THE EDIT UTILITY IS USED FOR INPUT 
MESSAGE EDITING, THE OUTPUT UTILITY FOR OUTPUT ERROR MESSAGE 
FORMATTINGs ANO THE CISPLAY UTILITY FOR QUTPUT MESSAGE TEXT 
CONVERSION TO AN OUTPUT UTILITY FORMATTING MESSAGE. 


| 

SHS SEREEREREEEEEE EEE ESE REGISTER USAGE ¥ FS EEREHERESEEEHEE ETRE SOE SS 
zee PARAMETER SAVE REGISTER +t 
+o SPA ADDRESS + 
+s INPUT MESSAGE ACDRESS india 
+++ BASE REGISTER FOR OUTPUT MESSAGE DSECT ++ 
es HOLD OUTPUT MESSAGE LENGTH + 
2 - UNUSED -—- ee 
ae - UNUSED = *% 
9% WORK REGISTER +s 
ees RETURN CODE ++ * 
oe BAL REGISTER ees 
#2 BASE REGISTER e*% 


eee SAVEAREAC(WORKAREA CSECT) ++ 
HETERO EERE EEE REE EEE EES EEE EERE REE EEE E EEE ER ERR EEE EEE EEE EEE EEE EEE EE 


REGS 

26+* EQUATE RN NAMES TO ALL GENERAL PURPOSE REGISTERS 

27+ LAST REVISION 12/10/68 
28+RO ECU 
29¢R1 EQU 
30+R2 EQU 
31¢R3 EQU 
32+R4 EQU 
334R5 EQU 
34+4+R6 EQU 
35¢R7 EQU 
36¢4R8 EQU 
37+R9 EQU 
38¢+R10 EQU 
394#R11 EQU 
40¢R12 EQU 
41¢«R13 EQU 
424R14 EQU 
43¢+R15 EQU 


Oonoufl une Oo 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
(Page 1 of 10) 
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PRINT NOGEN 
SQASM  § CSECT 
PREKEEHEEEREEEREREEERERREOREEEEEESEEEERSEEERESEEFEDEESEEESDEEHEEDEEEEREEEESE 
% PROVIDE LINKAGE AND OBTAIN CORE * 
SHHAEAKERERAEERRERAEREEEEEORREREREE REESE RE EEE SHEER ES OEEEEEEEEEEEEEEEERESD 

USING INMSG ,R4 

USING DUTMSGsR5 

USING WORKAREA,R13 

LINKAGE BASE#(R1Z) sLEN*@DYNLEN sPARM#(R2Z) o> SPA®(R3) gp MSGB(R4) 5 

OSECTS=(SCT»MSGeR13) 

PRINT NOGEN 

PRINT NOGEN 

PRINT GEN 

PUSH PRINT TURN OFF PRINT GENERATION 

PRINT NOGEN 

PCP PRINT RESUME PRINT GENERATION 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
(Page 2 of 10) 
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PRINT NOGEN 

MVI ERRMSG,C* ° BLANK ERROR MESSAGE AREA 
MYC ERRMSG¢1(L*ERRMSG=1L) sERRMSG 

SR R105R10 SET RETURN CODE TO ZERO 


SHSSHCSE HSE HHS KERSEKSEEESEEREKEESES HERSEK EKER EEKASCEKEKRREEEESEEESESREESS 
¢ INVOKE EDITCTRL 
HERRERA EAE EERE EREEEE EERE KER EERE EEE EERE ERE EER EEREEEEREREER ES 
MAPINPUT DS OH 

CALL EDITCTRLo((R4)9(R3) 90) 9 VL es MF=(EyPARMSAVE) 

LTR R159R15 EDIT OK ? 

BZ MSGOKAY YES 

LA R1054 NC - SET RETURN CODE 
¢ NOTE? EDIT UTILITY RETURNS ERROR MESSAGE 

B RETURN EXIT (NO MSG TO FREE) 
MSGCKAY DS OH 

L R4y»PARMSAVE LOAD EDITED MSG ADDRESS 

ST R4,IMSGADDR SAVE MSG ADDR FOR LATER FREE 
SHSPSESHESKKSHSESR ESE SKA SEKEVERSE SESH ERK SKE EKREKEKESEEEEEKREEEEESESE HEED SE 
* PREPARE TO SELECT AND ACCESS BDAM FILE * 
EPREAREAA HSER EEEEAERE SEE ROEEEEREAEE HERE EERE EERE EER EEEREAEEEREEE DR EEE 

MVC CLRRFILEy=C*PARTFILE*® ODD NAME OF BDAM FILE 

BAL R11lsSELECT SELECT THE FILE-EXIT IF NO GOOD 

PACK DASLWORD»RBNBYTE PACK RBN DIGIT INTO DOUBLEWORD 

CVB R9,DBLWORD CONVERT TC BINARY 

ST RSsFULLRBN RBN FOR ACCESSING BDAM FILE 

CALL READ» (EXTDSCT»FHCWsBDAMFILE »RBN) 9 VL gMF@(EgP ARMSAVE) 

CLI FHCW,C*o! WAS READ SUCCESSFUL? 

BNE BDAMERR KO 

BAL R11lsRELEASE RELEASE THE FILE 

CLC PARTNOsPARTNUM DO WE HAVE THE CORRECT RECORD? 

BNE NOTFOUND NO 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
(Page 3 of 10) 
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THERESE EEEE EE EEERESEEEEEEEESESEESEEE EEE REE EE SHEEEEEE HES EEEEEEEEDE HEED 
bd PREPARE TO SELECT AND ACCESS VSAM FILE + 
SHEARER SERERAE ERE REE EEE EE SEE SH EEEEE EERE EE EEE EE EEEOEE SHEE EEE HRESR EERE SEE ES 

XC EXTDSCT,sEXTOSCT CLEAR EXTOSCT 

MVC CURRFILE »*C*STOKFILE' DONAME OF VSAM FILE 

BAL R11,SELECT SELECT THE FILE-EXIT IF NO GOOD 

MVC KEYPARTsPARTNO FORMAT KEY FOR VSAM GET 

MVC KEY WHS »WHSNO VSAM KEY NCW COMPLETE 

CALL GETVs(EXTDSCT sFHCWsVSAMFILEs VSAMKEY) »VLyMFe(E,PARMSAVE) 

CLI FHCW,C'0O! WAS GETV SUCCESSFUL? 

BNE VSAMERR NO 

BAL R11,»RELEASE ROUTINE TO RELEASE FILE 

LA R6sOUTMLEN SET QUTPUT MSG AREA LENGTH 

BAL RL1sGETOMSG GET AND INIT QUTPUT MSG AREA 

B MOVE INFO SET OUTPUT TEXT AREAS 


REKEREEREEAEREREREEEREEEE EERE EE EE EERE SE EEREERESEEEEEEEEREEEEEEEEE SESE S 
* SELECT, RELEASE, ANC QUTPUT MESSACE "STORAGE® ROUTINES + 
EKKERAPESREEEE SEE SEEEERERE EERE ERE EREREARE EERE EE ERSTE REREDEKERE EEE S 
SELECT DS OH 

MVC FHCWsBLANKS CLEAR FILE HANDLER CONTROL WORD 

CALL SELECT s(EXTOSCTsFHCWsCURRFILE) »VLoMF2(EsPARMSAVE) 

CLI FHCW,C*O? WAS SELECT SUCCESSFUL? 


BNE SLCTERR NO 
MVC FHCWsBLANKS CLEAR FHCW FOR I/O 
BR Rll BRANCH BACK 


RELEASE OS OH 
CALL RELEASE s(EXTDSCTsFHCW) sVLoMF=(E sPARMSAVE) 
BR R1l BRANCH BACK 


GETCMSG DS OH 

STORAGE ADDR*OMSGACCRseLEN#(6) sLIST*PARMSAVE 9S PA#(3) 

LTR R15sR15 WAS STORAGE ACQUIRED ? 

BZ CONT YES 
R1038 NO CORE RETURN CODE 
FREEIN NOTHING CAN BE DONE=GO BACK 
OH 
R4,IMSGADDOR RELOAD INPUT MSG ADDRESS 
R5,OQMSGADDR LOAD QUTPUT MSG ADDRESS 
MSGHLEN(MSGHLNTH) »0(R4) MOVE INPUT MSG HEADER 
R6yMSGHLEN STORE CUTPUT MSG LENGTH 
MSGHQPR»C*2° SET QPR = SINGLE SEGMENT MSG 
MSGHSSCHsMSGHRSCH SET HI-ORDER SENDING SS CODE 
MSGHSSCsMSGHRSC SET LO-ORDER SENDING SS CODE 
MSGHRSCH,0 SET HI-ORDER RECETWING SS CODE 
R11 BRANCH BACK 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
(Page 4 of 10) 


172 


Chapter 13 


Subsystem Testing in Test Mode 


L0G5 SEHK EEEE EERE EHEEEEESEEE EEE EE EEEEEECESSESEOEHEE EEE HEE ES CHEE RES ED 
MOVE DATA FROM FILES TO GUTPUT MESSAGE AREA * 


& PACKED INTERNAL FIELOS ARE PRE=-EDITED FOR DISPLAY UTILITY * 
LO6G FREAK EEEEE RES EEE EEEE EEE EERE EEE EERE EER ERE EREREREEEEEEEEEREEEEEEE 


1066 
1067 


1069 
1070 
1071 
1c72 
1¢73 
1074 
1C75 
1C76 
1c7?7 
1C786 
1079 
1080 
1081 
1082 
1083 
1084 
1085 
1086 
1¢87 
1¢88 
1€89 
1090 
1091 
1092 
1093 
1094 
1¢€95 
1096 
1097 
1c98 
1099 
1110 
1111 
lll2 
1113 


* 


MOVEINFO DS 
NVI 
MVI 


OH 

MSGHRSC,CtHE 
MSGHVMI,x'72° 
FMTNAME »DISPNAME 
OUTWHSNO(2),B8LANKS 
OUTWHSNO+2 (3) »wHSNO 
PRTDATAsPARTNUM 
PRCEDIT,sEDITPRC 
PRCEDITsPRICE 
PRTPRC,»PRCEDIT 
WHSLCC WHS 
NUMEDITsEDITNUM 
NUMEDIT,SLEV 
STKLEVsNUMEDIT#1 
LEVDATE(2),SDATE 
LEYDATE+2,C*/?* 
LEYDATE#3(2),SDATE+2 
LEVDATE*+5,C*/' 
LEVDATE+6(2) sSDATE*4 
NUMEDIT,EDITNUM 
NUMEDIT»,OLEV 

STKORD »yNUMEDIT#1 
ORODDATE(2) ,ODATE 
ORCDATE+2,C*/! 
ORDOATE?#3(2) ,ODATE+2 
ORDDATE+5sC*/'* 
ORODATE+6(2),CDATE+4 


SET RSC FOR DISPLAY SS 

SET VMI FCR DISPLAY SS 

FILE DESCRIPTION RECORD NAME 
LEADING BLANKS NEEDED 
WAREHOUSE NUMBER 

PART #5 DESCRIPTION, UNITS 
MOVE EDIT PATTERN TO WORK AREA 
EDIT UNIT PRICE 

PRICE 

WAREHOUSE 

MOVE EDIT PATTERN TO WORK AREA 
ECIT STOCK ON HAND 

STOCK LEVEL 

MONTH 


DAY 

YEAR 

MCVE EDIT PATTERN TO WORK AREA 
EDIT STOCK ON ORDER 

STOCK ORDER 

MONTH 

DAY 


YEAR 


EKSEKSKEKEBERHEEKEHEE HEHE SEEKERS EES EKEEESEHRESEEESEREEEEEHEE EEE EE ESE 


* 


INVOKE MSGCOL TO QUE 


UE MESSAGE FOR DISPLAY UTILITY * 


REE ERE AERA AKE SRE AEE ARERE AREER E EEE EERE EERE EER OEEEK EEE EEE ES 


CALL 
LTR 
BZ 
LA 

B 


MSGCCL9((5) 903) ) 9 VL 
R15sR15 

FREEIN 

R10,8 

FREEIN 


MF=(EysPARMSAVE) 
SUCCESSFULLY QUEUED? 
YES 

NO CORE RETURN CODE 
EXIT 


1114 PRINT NOGEN 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
(Page 5 of 10) 
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LLL SHSERSCEHE EEE EEE EE EERE ERESE RHEE EEE EES TERESA SEES EEEEE SE EEERES SEEDED 
1117 * FREE INPUT MESSAGE AREA AND RETURN * 
LILO SFHEREE EHH REE ERERE EERE EE EERE EEE EEE EE ERE ORE EERE EEEEEEEEEEEE SS 
1119 FREEIN DS OH 

1120 L RlyIMSGADDR RELOAD INPUT MSG AODRESS 

llél LH RO,O(R1) LOAD MESSAGE LENGTH 

1122 STORFREE ADOR#(1) ,LEN#(0) sSPA*(3) 

1123+ PRINT NOGEN CH 
1126+ PRINT GEN CH 
1129+ N Os=X "OCFFFFFF ® ENSURE SUBPOOL BYTE IS CLEARED. 
1130+ L 15,SPAFREE=SPALST(3) . LOAD STORFREE RCUTINE ADDR SK 
1131+ BALR 14515 CALL ROUTINE. 

1132 RETURN DS OH 

1133 PRINT NOGEN 

1134 RTNLINK ADDR#(R12) sLEN=DYNLENsRC#(R10) RETURN CONTROL 
1144+ PRINT NOGEN 


Subsystem Testing in Test Mode 


1180+*,GETSPA - V7.0 -— 11/76 = SM 


1204 
1205 
1206 
1207 
1208 
1209 
1210 
1211 
1212 
1213 
1214 
1215 
1216 
1217 
1218 
1219 
1220 
1221 
1222 
1223 
1224 
1225 
1226 
1227 
1228 
1229 
1230 
1231 
1232 
1233 
1234 
1235 
1246 
1247 
1248 
1249 


PHESKEARESRERESEEE EERE REESE ERE EEEEREEEREEER EEE SEEEE EEE EEEEEEEEE SEES S 


* ERROR PROCESSING * 
SHOTS SEEKERERSEHSESSESEKSSREKREEAERSR ESE KERSEEREREREEHRESEESESEEEESEESEEESEEEES 
SLCTERR ODS OH 
MYC ERRMSG(8) »,CURRFILE MOVE FILE NAME 
MVI ERRMSG+9,C'-'! . 
MVC ERRMSG4+11(L°SLCTMSG),SLCTMSG SELECT=ERROR MESSAGE 
B DOERRMSG 
NOTFOUND OS OH 
MVC ERRMSG(L*NCFNDMSG) »sNOFNDMSG ELUSIVE=PART MESSAGE 
MVC ERRMSG+5(5) »PARTNO MCVE IN INVALID PART NUMBER 
B DOERRMSG 
VSAFPERR ODS OH 
CLI FHCW,C*2! RECORO NOT FOUND ? 
BNE BDAMERR NO = I/O ERROR 
BAL- R11lsRELEASE 
MVC ERRMSG(L*NOWHSMSG) »NOWHSMSG WRONG=-WAREHOUSE MESSAGE 
MVC ERRMSG4#5(5)sPARTNO MOVE IN INVALID PART NUMBER 
MVC ERRMSG+34(3) »sWHSNO MOVE IN INVALID WHS NUMBER 
B DOERRMSG 
BDAFERR OS OH 
BAL R11,RELEASE 
LA R10s12 I/O ERROR RETURN CODE 
: B FREEIN 
DOERRMSG OS OH 
LA R6,ERRMLEN SET ERROR MSG LENGTH 
BAL R11l,GETOMSG GET AND INIT CUTPUT MESSAGE AREA 
MVI MSGHRSC»C*U® SET OUTPUT UTILITY SS COOE 
MVI MSGHVMI,X*50° SET FORMAT MSG VMI 
MVC ERRORFMT sERRMSGID MOVE REPORT #, ITEM CODE, LENGTH 
MVC ERRORTXTsERRMSG MOVE ERROR MESSAGE TEXT 
CALL MSGCOLs((5)503))9VLsMFa(EsPARMSAVE) 
LTR R155R15 WAS MSG QUEUING SUCCESSFUL? 
BZ FREEIN YES - FREE INPUT MSG» EXIT 
LA R1058 WO CORE RETURN CODE 
8 FREEIN NOTHING CAN BE DONE=GOBACK 
Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
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CHEESE KEEEEHEREERESEEEEERAEREEAEEERERSREREREREEEEEEEEESEEERESEEEEEEEEEES 
* CONSTANTS * 
PETES ER EERE TEESE 5EEEEEEEEEEEE GEE EEEE EEE EEE EREEESEEEEERESEKEREEERES 
BLAAKS OC CL4* * 
SLCTMSG DC C*FILE COULD NOT BE SELECTED' 
NOFNDMSG OC C8'PART XXXXX NOT FOUND! 
NOWHSMSC DC C*"PART XXXXX NOT FOUND IN WAREHCUSE YyYyY* 
DISPNAPFE DC C*SSRQOOOL * FOR NAME IN CENGTB 
DC cta® FULL MESSAGE INDICATOR 
DC Cc! , USE OFT # IN FOR 
ERRFMSGIO DS OH ALIGNMENT 
OC X"FFO2 ° ITEM CODE» LEN FOR REPORT # 
DC H*501° ERROR MESSAGE OFT NUMBER 
oc X'F9! ERROR TEXT ITEM CODE (249) 
DC HL1'50° ERROR TEXT LENGTH 
EOITPRC OC C"'$" 4X"'2021204B20202020' PRICE EDIT PATTERN= $NN.NNNN 
EDITNUM ODOC X*40206B20202C6B202120' #4 EDIT PATTERN= NeNNNoNNN 
LTCRG 
=C*"PARTFILE* 
=C*STOKFILE' 
=X "OOFFFFFF * 
=V(PMIRTLR) 


Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
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SSS SESHESE SEES KEES SHESSEKESSS EK ESSESE SEEKS KESHESEEE EE HEEEEEEESEEEKEEREE EES 


* 


DSECTS 


* 


CREEKS EHHEEEESE THESE SEER EERESEEEEEEEE SHEE CERES EEEEEREEESEESEEERES OEEEEEEES 


WORKAREA 
SAVEAREA 
IMSGADDR 
OMSGADOR 
PARMSAVE 
OBLhORC 
FHCh 
EXTOSCT 
FULLRBN 


RBN 
VSAMKEY 
KEYWHS 
KEYPART 
CURRFILE 
BDAMFILE 
PARTNUM 
DESCRIPT 
UNITS 
PRICE 
MER 
UNUSED1 
VSAMFILE 
DELETE 
KEY 
UNUSED2 
WES 

SLEV 
SDATE 
OLEV 
ODATE 
ERRMSG 


NUMEDIT 
PRCEDIT 


DYNLEN 


INMSG 
PARTNO 


RBNBYTE 
WHSNO 


Figure 56. 


DSECT 
DS 18F 
os 
BS 
DS 
DS 
DS 
OS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
OS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
OS 
DS 
ORG 
DS 
OS 
ORG 
ECU #-WORKAREA 


DSECT 


176 


ADDRESS OF INPUT MESSAGE 
ADDRESS OF OUTPUT MESSAGE 

6 IS MAX NUMBER OF PARMS PASSED 
USED IN CREATING RBN 

FILE HANDLER CONTROL WORD 

BDAM AND THEN VSAM CONTROL AREA 


USED FOR ACCESSING THE S8DAM FILE 


100 BYTE BOAM RECORD BEGINS HERE 


8O BYTE VSAM RECORD BEGINS HERE 


REUSE AREA FOR NUMBER EDITING 


TOTAL DYNAMIC WORKAREA LENGTH 


MESSAGE HEADER 
PART NUMBER 


FOR BOAM FILE ACCESS 
WAREHOUSE NUMBER 


Sample Inquiry Subsystem; Reentrant Assembler 
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1322 
1323 
1324 
1325 
1326 
1327 
1328 
1329 
1330 
1331 
1332 
1333 
1334 
1335 
1336 
1337 
1338 
1339 
1340 
1341 
1342 
1343 
1344 
1345 
1346 
134? 
1348 
1349 
1350 
1351 
1352 
L253 
1354 
1355 
1356 
1357 
1358 
1359 
1360 
1361 
1362 
1363 
1364 
1365 
1366 
1367 
1368 
1369 
1370 
1371 
1372 
1373 
1374 
1375 
1376 


Subsystem Testing in Test Mode 


CLIMSG DSECT 
COPY MSGHDRC MESSAGE HEADER 
* 
¢ MESSAGE HEADER LAYOUT 
’ CORTES EEE REE ETE EE EEE 
* LAST REVISICN 10/20/82=RELEASE 9.0 
* LAST REVISION 07/30/85-LU 6.2 SUPPORT 
" 
MSCFLEN ODS BL2 LENGTH OF MESSAGE 
PSGFQPR OS BL1 CTAM/BTAM 1/0 PREFIX BLANK IF SS MSG 
MSGHRSCH DS XL1 FI-ORDER BYTE OF RECEIVING SUBSYSTEM CODE 
MSGHRSC OS Cll RECEIVING SLBSYSTEM CODE 
MSGFSSC DS Cll SENDING SUBSYSTEM CODE 
MSGFMMN ODS OBL3 MONITOR SEQUENCE NUMBER X1078 
MSCFTXTL DOS BL2 RECORD LENGTH (FILE RECOVERY) X1078 
MSGFKEYL DS Cll KEY LENGTH (FILE RECOVERY} X1078 
MSGHDAT ODS OCL6 CATE (YY.CO0) X1078 
MSGEYR DS ClL2 YEAR X1078 
MSGCFTHRD OS BL1 THREAD NUMBER X1078 
MSGHOAY OS CL3 DAY x1078 
MSGHTIM ODS CL8 TIME (HH eMMeSS) 
ORG MSGHTIM FIELDS USED IN SCANVERB DURING JA 
+ CONSTRUCTION OF MESSAGE IN LINE HANDLERS JA 
MSGFRVYFLG DS B FLAGS JA 
MSGHVFND EQU x*8o! VERB WAS ANALYZED BEFCRE CALLING BTSEARCH JA 
MSGHVBA OS AL3 A(BTVERB ENTRY) IF MSGHVFND FLAG ON JA 
ORG MSGHTIM4L *MSGHTIM JA 
MSGFTID ODS CL5 TERMINAL ID (AAANN) AAASCITY,NN#DEVICE ID 
MSGHMROX OS Ox INDEX TO MULTIREGION MCT ENTRY 
MSGRCON ODS BL2 COMPANY NUMBER 
* SPECIAL VALUES CF MSGHCON JA 
MSGRCFLA EQU X*BBO1* FLUSF=-ALL CHASER MSG JA 
MSGHCP12 ECU X*BB03' 32270 COPY FORM 1 (REMe-SAME CU)s2 (3275—-hWR) JA 
* MSGHCP12: COPY TYPE 1 OR 29 ISSUING TERM REQUEST RESPONSE SM1124 
MSGFCN12 EQU X*BB13° COPY TYPE 1 OR 2s NO RESPONSE TO ISSUER SM1124 
MSGRCP3 ECU X*BBO2'* 3270 COPY FCRM3 (READ FULL BUF REQUEST) JA 
MSGHR129 ECU X"*BBO4' IBM129 CARD READER RESET I[/P INHIBITED MSG JA 
MSGFFEVYR EQU X"'BB’* SET IN MSGHCON+1 OF RESPONSES TO F.E.VERBS JA 
ORG MSGHCON+¢1L 
MSGHRETN DS BL1 RETURN COCE. 
MSGRFCONV EQU c*C* 30 LOGGED FROM CONVERSE. 
MSCFFLGS OS OFL2 MESSAGE INOICATOR FLAGS SM1166 
MSGHFLG1 DS FL1 PESSACE INDICATOR FLAG=BYTE=1 SM1166 
MSGHFSOR €CU x "80° ASK FOR DEFINITE RESPONSE VTAM 
MSGFFSER EQU x'40° ASK FOR EXCEPTION RESPONSE VTAM 
* IF MSGHFSDR*MSGHFSER20 THEN NO RESPONSE VTAM 
* SPECIFICATIONs USE OTHER SOURCES TO DETERMINE. VTAM 
MSGHFRSP ECU MSGHFSOR*MSGHFSER MASK TO CHECK ‘*SRESP'§ VTAM 
MSGHFSR1 ECU x'20! 1 -> RESPONSE TYPE 1 (CFME) VTAM 
MSGFFSR2 ECU x*10° l1 => RESPONSE TYPE 2 (RRN) VTAM 
MSGHFSEB EQU x'08! SEND EB WITH THIS MESSAGE VTAM 
MSGRNCON ECU X"O4! DO NOT CANCEL CONVERSATION TIMEQUT XMO215 
MSGHFNF3 ECU x'C2° 1 => DONT WRITE X°F3* LCG RECORD FCR MSG 
MSCFKFRLS EQU x*o1' RELEASE NEXT QGUTPUT MESSAGE SM1166 
* SM1166 
Figure 56. Sample Inquiry Subsystem; Reentrant Assembler 
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1377 
1378 
1379 
1380 
1261 
1382 
1383 
1364 
1285 
1286 
1387 
1388 
1289 
1390 
1391 
1392 
1393 
1294 
1395 
1396 
1397 
1298 
1399 
140C 
1401 
1402 
1403 
1404 
1405 
1406 
1407 
14C8 
1409 
1410 
1411 
1412 
1413 
1414 
1415 
1416 
1417 
1418 
1419 
1420 
1421 
1422 
1423 
1424 
1425 
1426 
1427 
1428 
1429 


MSGHFLG2 DS 
MSGHFTRM ECU 
MSGHSRST EGU 
MSCFSYSC EQU 
* 
MSGHFMHI ECU 
* 
MSGFBMN DS 
* 
MSGRPMN EQU 
MSGHSSCH DS 
MSGRUSR ODS 
ORG 
MSGRHADDR DS 
ORG 
MSGHBKID DOS 
MSGFDO DS 
MSGRHLOG OC 
RVZONE EQU 
RCZONE ECU 
MSGRFXFIL EQU 
RCSTUP EQU 
MSGHROQST ECU 
MSGHROND EQU 
MSGHRBUF DS 
MSGFMACR DS 
MSGHBLK ODS 
MSGHVMY OS 
MSGFFFVM EQU 
DDQVMI EQU 
* 
MSGHEND EQU 
MSGHLNTH EQU 
* 
OUTTEXT OS 
FMTNAME ODS 
PRTCATA OS 
PRTPRC DS 
QUTWHSNO DS 
OUTSDATA DS 
WESLOC DS 
STKLEV DS 
LEVDATE ODS 
STKGRD DS 
QROCATE OS 
DS 
CUTMLEN EQU 
ORG 
ERRCRFMT DS 
ERRCRTXT OS 
DS 
ERRMLEN EQU 
END 
Figure 56. 


¥L1 

KL1 
MSGHUSR 
AL3 
MSGHTID 
CL8 

CLs 
c*o* 

x' 80° 
x*'90° 


RV ZONE +15 
RCZONE+15 


MSGHEND<-MSGHLEN 


OCL147 
CL1i2 
CL64 
CL9 

CL5 
OCL57 
CL23 
CL9 

CL8 

CL9 

CL8 

OC 
*-OUTMSG 
OUTTEXT 
CL6 


*-OUTASG 


Subsystem Testing in Test Mode 


MESSAGE INDICATOR FLAG-BYTE-2 
PSGFADOR PCIATS TO SOURCE BTERM/LUC 
SERTALLY RESTARTED MESSAGE INDICATOR 
CUEVE THIS MSG TO A 642 SESSION EVEN 
IF NO CONVERSATION CURRENTLY ACTIVE 
THIS MESSAGE CONTAINS 6462 FMHDR 


BTAP SEQUENCE NUMBER 


HI/ORDER BYTE OF SENDING SUBSYSTEM 
AVAILABLE 30 USER 


ADORESS OF AN AUXILIARY AREA (FE ONLY) 
FOR FILE RECOVERY 
BOAM BLOCK IO (FILE RECCVERY) 
FILE DONAME (FILE RECOVERY) 
LOG TYPE CODE -SEE MONITOR WRITEUP 
FILE REVERSAL ENTRY. 
FILE RECREATION ENTRY 
CHECKPOINT RECORD. 
STARTUP RECORD. 

LOGPROC REQUEUEING STARTED. 
LOGPROC REQUEUVEING ENDED. 
BUFFER LENGTH (BDAM FILE RECOVERY) 

FILE FANDLER MACRO # 
BLANK (BINARY ZERO) 
VERB/MSG ID 


SPECIAL VMI FCR FULLY FORMATTED MSGS 


SPECIAL VMI FCR DYNe DATA QUEING 


TEXT AREA 
FIXED FORMAT AREA 


PART #» DESCRIPTION, UNIT TYPE 


PART PRICE (EDITED) 


LENGTH OF MESSAGE HEADER 


3M1166 
$M1166 
(9.0) CH 


31MD 
51MD 


xX1078 
JT 


JA 
MM 


WAREHOUSE NUMBER (LEADING BLANKS) 


STOCK DATA 

WAREHOUSE SITE 

WAREHOUSE IN STOCK €EDITED) 
WAREHOUSE LEVEL DATE 
WAREHOUSE ON ORDER 
WAREHOUSE ORDER DATE 
ROUND UP MSG AREA 
OUTPUT MSG AREA LENGTH 


(EDITED) 


ERROR MSG OFT #» ITEM CODEs LEN 


ERROR TEXT AREA 
ROUND UP MSG AREA 
CUTPUT MSG AREA LENGTH 


Sample Inquiry Subsystem; Reentrant Assembler 
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//TABLES 
DEFINE SYCTTBL FOR SUBSYSTEM 


EXEC LIBELINK,Q=TEST ,NAME=INTSCT , LMOD=INTSCT 
//LIB.SYSIN DD * 
./ ADD NAME=USRSCTS 
./ NUMBER NEW1=100 , INCR=100 
USRSCTS DS OH 
RA SYCTTBL SUBH=R , SUBC=A, SBSP=SQASM , LANG=RBAL, OVLY=0, 
NUMCL=10 ,MNCL=1 , TCTV=60 
/* 
//ASM.SYSIN DD DSN=INT.SYMREL(INTSCT) , DISP=SHR 


DEFINE EDIT CONTROL TABLE ENTRY 


EXEC LIBELINK,Q=TEST,NAME=PMIVERBS , LMOD=PMIVERBS 
//LIB.SYSIN DD * 
./ ADD NAME=USRVERBS 
_/ NUMBER NEW1=100, INCR=100 
USRVERBS OH 
| RTRAECT RTRA,D9,256,2, FIX=YES 
P/N,1,7,5,10000111 
WHS ,2,7,3,10000111 
/* 
//ASM.SYSIN DSN=INT . SYMREL(PMIVERBS) , DISP=SHR 


DEFINE CHANGE/DISPLAY TABLE 


EXEC LIBELINK,Q=TEST , NAME=CHNGTB , LMOD=CHNGTB 
//LIB.SYSIN DD * 
./ ADD NAME=CHNGTB 
./ NUMBER NEW1=100 , INCR=100 
CHTB TITLE 'CHNGTB - FIXED FORMAT OUTPUT-DESCRIPTOR NAME TABLE’ 
CHNGTB CSECT 
DC  CL8’SSRQO001’ USED ONLY TO TEST BAL PGM. GUIDE S/S 
DC F’0 
PMISTOP 
END 


Figure 57. Table Updates to Implement Test Mode Testing 
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0O0€E0000 
002€0000 
0OOTEDDDD 
000€0000 
00620000 
00820000 
00220000 
00920000 
00520000 
00420000 
00€20000 
00220000 
00TZ20000 
00020000 
006T0000 
OO8TO000 
00ZTOO000 
TO9TOO0D 
00ST0000 
00%TO000 
O0OeTOO0O 
002T0000 
OOTTON0O 
000TO000 
00600000 
00800000 
00200000 
00900000 
005600000 
00%00000 
00€00000 
00200000 
00T00000 


GyeQl* @€ewOdd*9T #39009 

GEzOlSTE=WOdd*,dAD SV,2V1LV0°SS22#309)9 
E2201 °ST=wOdd' ST =#3009 

ET#O0L*9seWOud® ~xadYO NOs=V1LVI°SS2=#500)9 
YaSWwILI*@=wnn 

GE=OLSTEsWOdds AD SVe8V1V0°SS22390)9 
Gy=D0l*QEewOdds oT=#300)9 
E2=D1*ST=wOdd*€T #3009 

2T#OL*9swOdds,INVH NO.#ViV0%SS2239009 
y=eSWALIS2Z=Wnn 

G€=D0L*€TewOdd*OT#3009 

TT#OlS venous ® NOILVIOT. =VLV0°SS2=5009 
C=SWILITS9O=WNN 

TE#01S22=WONd* 8239009 

GZ2eJ LS TaeWOdd® sSSNOHSYVM LV SNLVLS HIOLS.#V1V0'SS72=90I99 
Z=SWILI*S=Wnn 

€€=01*S2=wOdd* 61 #39099 
E22OLSST#WOdd® ADI Ud VIVO °SS2=59099 
ZTsOLS€T=WwOUd*e@T=3009 

TT#OL*TeWwOuss «SLINA Y30UO. FVLV0'SS223009 
beSWALlLI*>=Wnn 

99=201S€T=wOud* t2#40)9) 

TT#OLS TeWwOdd* NOI Ld I 498390, sV1LV0°SS22309) 
ceSWALI*Se€=Wnn 

LT=OLSET=wOds* 2023009 

TT#OLS T2wOds* syaSGWNN Ldvds #VLV0°SS2#3909) 
fCeSWILIS2=WNNn 

622015 9sWOUSSs LSINOAY SILVLS AIILS.*VLV0*SS2=3500)9 
TaSW3ILI*TsWwnn 


ON3 
WILT 
WALI 
WALT 
WALT 
JNT1 
WILT 
Wall 
WILT 
W31T 
INI 
W31TI 
WALT 
INIT 
WALT 
WILT 
INI 
Wall 
WALI 
WILT 
WALI 
INI 
WILT 
WILT 
ANI 
WILT 
W3Ll 
ANT) 
W3LI 
ANT 


S=SINITSOOT#WAN LYOd3dy 


LvO9T9 


Quost) 


LO1¥T9) 
AI 1eT) 


J TMOTS 


SHM8) 


JYd6T) 


INN8TO 


$i0T2) 


ONd2T) 


OOTLI0 
* 


WALSASAHNS AMINONI JAldwWV¥S wOd AIGVL LVWYOFI INdLNO + 
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00ST0000 GNI 

00%1T0000 9T23099*XXLOD=3SWVNSO2N597S92T2#1398S50 11304 9T100 
OOETOOOD GT#3099*XXGYOs4WVNS62NSTS2ZTT#13S40 113043 STQuO0 
002T0000 bT=3009*XXLOT#=3SWVNS82N3971°60T215S50 11404 bT107} 
0OoTTO000 ET#3009* XXAIT#IWVNS 62N57600T#L13S40 W304 ETA] 
000T0000 OT#3099*XXI TMBIWVNSE2ANITS2221395S8S40 1304 OT IM 
00600000 823009 XXSHM*BIAWVNSGENA1*222145S50 11404 BOSHM 
T0800000 61 =3009*XXIad=3WVNS 62N37°492139S40 113504 STIUd 
00200000 @T=3009*XXLNN#3WYNSS2N37°6G213S40 11504 BTINN 
00900000 T229009°XXS3IG=3WVN £4GHN391°G6219S40 11304 T2$30 
00600000 2T# 3009S XXN/ d= SWVN*SON97SO0219S40 11304 2TONd 
00400000 OT*SATATIASOOT#=ONI de® TOOIDYSS#4WYN YGHOI OOTOYSS 
00€00000 ) 194$9 10000830 
00200000 WILSASENS AYINONI AldWVS WOU * 
00T00000 LAdLNI LVWdOd AAXTIA YOd AYOITA NOTIdI ISIC Jd + 
00200000 ONS 

00900000 29201S2T#WOdd*64225009 WALI 

00600000 oe ee UNNI ee peVIVOS OT AOL S T=w0dd*SS22400) WIL! 

00%00000 C=SWAILIST#WAN JSNI1 

00€00000 T#SINIVSTOS#WAN LYOd3dy T0S140 


00200000 % 
00T00000 WALSASONS AMINONI WOUd SAIIVSSAW wOUYS YOd JWVL LVWHOS INdLNO » 
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MSG 


Low-order byte of S/S code (MSGHRSC) (or 8) 


Hi-order byte of S/S code (MSGHRSCH) (or 11) 


Sending terminal ID (MSGHTID) 


Front-end Message Number (MSGHBMN) 
VMI value (MSGHVMI); leave blank if EDIT 
required; code 255 if no editing by Edit 
| Utility (or 57). 
DETAIL(s) Data for one line of input message. If VMI 
in header card is left blank, a new line 
character is inserted at end of text on ever 
card except last one. If the last non-blan 
character is a § sign (X'5B’), it will be 
replaced by a NL; the preceding character 
(usually a blank) is kept as part of the 
input. All NL’s are suppressed if editing is 
not required. 
TRAILER Generates End of Transmission characte 
following the last non-blank character of th 
previous detail card. 


Contents Ending 
of Card Character 


EMS EOT (X'37') 
EOT EOT (X'37') 
ETX ETX (X'03") 
ETB ETB (X'26') 


*3-digit integer values (from 000 to 255) or a corresponding single 
alpha-numeric character in low-order field position. 


**64 is default maximum. See the Operating Reference Manual if 


necessary to alter this specification. 


Figure 59. Test Mode Message Card Formats 
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MSG A 
RTRA 

P/N 12345 
WHS 200 
EMS 

MSG A 
RTRA 

P/N 55555 
WHS 200 
EMS 

MSG A 
RTRA 

P/N 12345 
WHS 30C 
EMS 

MSG A 
RTRA 

P/N 12349 
WHS 200 
EMS 

MSG A 
RTRA 

P/N 12341 


P/N A2345 
WHS 400 
EMS 


Figure 60. Sample Input Test Messages for Test Mode 
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J/EXECTEST JOB CICOMTEST y»92C)e* ICOM TEST SCASM"»CLASS=A, 
/t RESTART=(GENLINK.ASM) 
//PRCCLIB OD OSN#INT.PROCLIBsOISP#SHR (AS NEEDED) 
J [PERE HEEEHE ETE SHEETS EE SES EHOHESH SE SHE SEES ESAS HEE ESTHSEE SESE RESET EES 
//* THE RESTART PARM IN THE JOB STATEMENT RESTARTS THE TEST AT THE + 
//* BEGINNING. IF YOU wKISH TO RESTART AT A DIFFERENT STEP» CODE * 
//* RESTART*STEPNAME GR RESTART*STEPNAME.PROCS TEPNAME . 
//* + 
//* NOTE? WHEN USING A WSAM FILEs IT MAY BE NECESSARY TO EXECUTE * 
//* IOCAMS TO VERIFY ThE FILE ITF A PREVIOUS EXECUTION ABENDED. * 
[f[EPRECSH REET EEH EEE HEHEHE ES ESHER OREEEDEE EERE SETHE HE EEE EE EE EEEE SESE DS 
//* 
J [PEHEHEE EERE SHER ERESENE ERE TE EEEH SHEESH ESHHESTE SEES SEETHER EERE SESE ES 
//* STEP GENLINK GENERATES A STANDARD TEST MOCE LINKEDIT DECK * 
//* VIA ASSEMBLY OF THE ICOMLINK MACRO. + 
//* TRE GENERATED DECK (TESTLINK) IS PLACED ON INTeSYMTEST. * 
[FERS EHA EERE EEHER EERE SHAE EERE TESEEER EEE EEE HERE SEES OSES EERE E DE 
J/GENLINK EXEC ASMPCsQ=LIBsL#=REL »DECK=DECK 
//ASMASYSIN DD * 
ICOMLINK TEST#YES »sMMUSNO,STCRFECH#NG 
END 
//SYSPLNCH DD OSN#INT.SYMTEST(TESTLINK) sOISP=SHR 
//* 
[fPHEERAEREESEE EEE ERE SEEER EE EEE EEE SESE SEEEAEEE SES ESTE HERESEES EES ERERESS 
//* STEPS SCRSCR ANO ALLOCSCR DELETE AND RE“ALLOCATE THE LOAD * 
//* MODULE LIBRARY USED IN THE TEST (ALSO USED FOR DYNLLIB) + 
[J (PPPOE EEE EHE TEE HERE STEEEE EEE EERE EE HET EEHEERESHEEE EEE OEE SET EHEREE DEEDES 
J/SCRSCR EXEC PGM=IEFBR14 
//FILEL DO DSN#INToMOOSCR»DISP=(OLDsDELETE) 
//ALLOCSCR EXEC PCM@IEFBR14 
DO DSN@ INT eMOOSCR sDISP=(sCATLG) sSUNIT#SYSDAy 
OCB=INT.MODRELs VOL*®SER@INTOOL sSPACES(CY¥L 5913997) ) 


J SSSERSEHHSHHSEHEHSRAEEKSATHSHEEESHHEHEKEHEKRHERSE EESHEEHEHCSE SIS HEKERHSESEHHHEREE EEE S 

//* STEP GENINCL CREATES INCLUDE CARDS USEC BY THE LINK EDIT STEP * 

//* THE ADDED INCLUDE STATEMENTS ARE FOR THE SAMPLE SUBSYSTEM ANC * 

//* THE REFERENCED CFTS (INCLUDE AFTER PMIRCNTB). * 

//* YF THE TEST1 TERMINAL IS NOT IN THE SYSTEM PMISTATB TABLEs ACOs * 

//* INCLUDE MODREL(CPAMISTATB) * 

//* INCLUDE MODREL(PMIDEVTS) * 

//* INCLUDE MODREL{PMIBROAD) * 

//* THE ABOVE ASSUMES THE CONTROL TERMINAL IS NAMED CATOI. * 

//* *#@ BEFORE THIS STEP» SEQUENCE NUMBER THE TESTLINK SOURCE, *#9¢* % 

JfSSHSSHHSSEHSHSESHESSEEHERSASHSHESSSSSSSHSHESSHS HOE SHEHSESSEEEEHEHESEHESHEKRE ES ES 

//GENINCL EXEC PCM#=IEBUPDTE 

//SYSPRINT OD SYSOUT#A 

//SYSUT1 oD) DSN*®INTeSYMTESTsDISP#SHR 

J/SYSUT2 OC DSNSEEINCL so DISP#( PASS) oUNIT#SYSDAsSPACES(CYL a (lelel) ds 

// DCB=(BLKSIZE#80,LRECL#80) 

J/SYSIN DOD * 

e/ CHANGE NAMESTESTLINK,LIST#ALL 
INCLUDE SYSLIB(SQASM) SAMPLE SUBSYSTEM 00c00010 
INCLUCE SYSLIB(RPTOO100) CISPLAY OFT FOR SUBSYSTEM 01981000 
INCLUDE SYSLIB(RPTO0501) ERROR MESSAGES OFT 019862000 


JCL requirements vary by installation requirements. The above 
example illustrates representative JCL. The installation 
System Manager should verify JCL to use. 
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[J [POSSE OHOTESHEEE ETE EER ESEE EEE OEE OEEE EEE EEO SOESEE OEHEEESEHESE SHEESH SERS 
s/* LINK EDIT THE TEST INTERCOMM SYSTEM 


* 
//* WOTE: THE INTERCOMM PROC “LKEOT® LINKEDITS MODULES FROM THE * 
//* SYSLIB CONCATENATION STREAM AS FOLLOWS —- * 
ss THE LOAD LIBRARY SPECIFIED BY TKE C= PARAMETER, * 
s/* FOLLCWED BY MCDULES FOLNO IN MOCUSR,» MCDLIBy THEN MOOREL. * 
//* THE INTERCOMM LOAD MODULE IS PLACED ON INT.MODSCR. * 
ff IT £8 NGT NECESSARY TO RE-DO THE WHOLE LINK TO REPLACE 1 MOCULE * 
/}* IN THIS CASE, ALL YOU SHOULD DO IS: * 
//* 1) REASSEMBLE OR RECOMPILE TRE CHANGEO/NEW MODULE INTO A * 
//* SEPARATE LOAD LIBRARY * 
//* 2) OQVERRIDE THE SYSLIN DO STPT TG //LKED.SYSLIN DD * * 
//* FOLLOW IT WITH INCLUDE CARDS * 
//* FOR THE MODULES YOU WISH TO REPLACE be 
//* 3) FOLLOW THOSE INCLUDES WITH THE FOLLOWING 3 CARDS: . 
//* IKCLUDE SYSLMOO(TESTICOM) * 
//* ENTRY PMISTUP * 
//* NAME TESTICOM(R) * 
//* 4) INSERT A OD STMT FOR THE LOAD LIBRARY ON WHICH THE * 
//* REPLACEMENT MODULES RESICE * 
//* 5) CHANGE THE RESTART PARM ON THE JCB STATEMENT * 
//* TO POINT TO THE LKED STEP * 
JfSSSESSSHSHSSESAEKESHEAESEESSHHSHSSSHSTHARKSES SEES SESH SE SKE REKE EERE EE 
//LKED EXEC LKEDT,»LMCC#TESTICOM,Q=TEST, 

4] PARMOLKED= "LIST »LETsXREF sNCALs SIZES( 250K, 1COK) ° 

/J/LKEC.SYSLIN CD OSN@EEINCL(TESTLINK) sDISP#(OLDyPassS) 

//MOQDREL 0D OSN*INT.MODREL»DISP#SHR 


Figure 61. Linkedit and Execution JCL for Test Mode (Page 2 of 3) 
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J SPSS SOSESEER SHEESH SHEESH KHTEESESK HSS SEPESSEH SSE SHEESH SESH STESCSES SHEERS TEES 
//* EXECUTE INTERCOMM IN TESTMODE * 
JS PESSSSHSESHTESSHEHTHESSESHE HESS SSE SEHE SETHE RESES SESH ESE SHESC HEHEHE SSESHESHE SHEE EES 
//6C EXEC PGM=TESTICOMsPARM=* TEST’, TIME=(,30) 
//STEPLIB OD DSN#INT.MOOSCR »DISP=(OLD,PASS) (OYNLLIB) 
oH) OSN@ INT. PMODUSReDISP#SHR (USER LOAD LIBRARY) 
DO OSN@INT.MOOLIBsDISP#ShR (SYSTEM UPDATE LIBRARY) 
0D OSN® INT .MODREL sDISP=SHR (SYSTEM RELEASE LIBRARY) 
//INTERLOG DO OSN#EEINTLOGsCISP=(NEWSPASS D5 
4/4 SPACE@(TRK»s (1055))sVCLSSER*®INTOO] »UNIT#SYSDA» 
// = CCB=(DSORG=PS ,RECFM=VB,BLKSIZE=4096 gLRECL #4092 »NCP=6 ,O0PTCO=C) 
//STSLOG OD SYSOUT#A,DCB2(DSORG=PS,BLKSIZE2#120,RECFM2FA) 
//S*4LOG OD SYSOUT#A,DCB=(DSORG=PS pBLKSIZE2120,RECFM=FA) 
//SYSPRINT DO SYSGUT#A,DCB#(DSORG#=PS sRECFM=VAsBLKSIZES141,LRECL2127) 
//RCTOOO OD OSN*INT.RCTCOO,DISP=SHR, 
// OCB=(DSORG=DA,OPTCD=RF) CUTPUT FORMATS 
//PMIQUE OD DISP#OLD,DSN#INT.PMIQUE, 
// DCB=(DSORG#DA,OPTCD=R) SUBSYSTEM DISK QUEUE 
//STCKFILE OD OSN#=VSAMSDO1.STCKFILE.CLUSTER»CISPSOLD» 
// AMP=(AMORG,s "RECFM=F ') VSAM TEST FILE 
//PARTFILE DD CSN=@INT.TEST.PARTFILEsCISP#OLD, 
4/ DCB=(DSORG#=DA ,OPTCD=R) BOAM TEST FILE 
//DESO0O0 OD OSN#INT.DESOOO sDISP=#ShR, 
// OCB=(DSORG=DA,0OPTCD=RF ) FILE DESCRIPTION RECORDS 
J/SYSIN DO OSN@INT.SYPTESTC(TESTMSGS) sDISP#SHKR,y 
// DCB=DSORG=PS TEST MCDE INPUT MESSAGES 
//PMISTOP DOD DUMMY 
//TCCMIN DO *# 
INTSTOROsICOMBDAMXCTRL 
/* 
/S/STEPCAT OD DSN#VSAMSD1,0ISP=2SHR VSAM CATALOG 
//DYNLPRNT OD SYSOUT#A 
J/DYNLWORK OD UNIT#@SYSDAsSPACE@(CYL 9 llsl)) sD ISPs PASS) 
/J/OVALLIB OD OSN#@INT.MOOSCR»DISPS(OLD»PASS) 
//* 
//SNAPDD OD SYSCUT#A 
J/SYSSNAP OD SYSOUT#A SNAP INPUT TEST MESSAGES 
J/SYSSNAP2 DD SYSOUT#A SNAP OUTPUT TEST MESSAGES 
//SYSUDUMP CO SYSCUT#A 
//* 
//ABNLIGNR DD DUMMY FORCE ABEND=AIO TO IGNORE OUMP (PRODUCE IBM CUMP) 
//* 
J SFSSHHSHSSERAESEH SSS SESHKREPEKRSESRSESHRE SEES SSE SESE SESEHEKESHEEESESEHEEEESEKE EES 
//* PRINT INTERCOMM LOG FROM TEST MODE RUN + 
JESSE HEHEHE HEHEHE HHEESEEETEEHEEESEEHEEBEHE ED 
//INTERLCG EXEC PCM=LOGPRINT»sCOND#@EVEN 
//STEPLI8 OD CSN#*INT-MODREL,DISP=#SHR 
J/SYSPRINT OD SYSOLT#A,O0CB=(DSORG=PS »BLKSIZE#121) 
//TINTERLOG OO OSN@GEINTLOGsDISP@SHRDCB@=BLKSIZE#5000 
J/SYSIN 00 DUMMY »,OCB=BLKSIZE=80 
4/ 
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Figure 62. 


"€9 san3tyy 


T6T 


(9 JO [ a8eq) AnoquTIAg Zo] uoTAnoexq epow yjsay 


DATE 89.199 TIME 12.56241 eet TN TER COAMMSA LOG DISPLAY #488 PAGE 1 
MSGLEN THREAD CPR RSC SSC MAN DATE TIME TIO FLGS USR BAN LOG BLK VMI 
78 0 O02 ee/CCOO0 -+-e/0CCO 1 89.199 12.56.3225 TEST1 0000 00 1 SF 00 00 
000000 CSD5E3C5 DIC3ID6C4 D440E2E3 C1D9E2E4 D74004C5 E2E2C1C7 C54C6040 C9D5E3E3 *INTERCOMM STARTUP MESSAGE - INTT® 
000032 FOFOF3E7 *003X * 
é5 0 O02 RA/DOC1L .«/0CCC 1 89.199 1225623225 TEST1 0000 00 1 QO1 00 00 
000000 O9E309C1 15076105 4OFIF2F2 F4F515E6 C8EZ4OF2 FOFO37 *RTRA.P/N 12345.-WHS 200. * 
65 0 O02 RA/OSC1 .-/CCO00 2 89.199 12.56.3226 TEST1 0000 co 1 oz 00 00 
0000co D9E3D9C1 15076105 40F5F5F5 FSF515E6 C8E240F2 FOFO37 *RTRAP/N 55555.WHS 200. * 
65 0 O2 RA/C9C1 .+/0000 3 8$.199 1225663227 TEST2L 0000 00 1 Ol 00 00 
0c0000 D9E3D9C1 15076105 40FLF2F2 F4F515E6 C8E240F3 FOFO37 *RTRAP/N 12345.WHS 300. * 
é5 0 C2 RA/09C1 .2/00C0 4 89.199 12.56.3228 TEST1 0000 00 1 01 00 00 
000000 D9E309C1l 15076105 40F1F2F2 F4F91L5E6 C8E2Z40F2 FOFO37 *RTRALP/N 12349.WHS 200. * 
65 0 02 RA/D9C1~ 2/9000 5 89.199 1225623228 TEST1 0000 00 1 01 00 00 
oooaco D9E3D9C1 15076105 4OFIF2F3 F4F115E6 C8E2Z40F1 FOFO37 *RTRAP/N 12341.WHS 100. * 
65 0 O02 RA/O9C1l 12/9000 6 89.199 1225623229 TESTI 0000 00 1 ol 00 00 
o000co 09E309C1l 15076105 40C1F2F3 F4F515E6 C8E240F4 FOFO37 *RTRALP/N A2Z345.WHS 400. * 
108 0 02 .U/00E4 ../0000 7 85.199 12.56.3256 TOALL 0000 00 0 01 00 50 


0c0000 FFO2002D 013C5C5C 5C40C7D6 06C440C1 C6E3C5D9 05060605 5C5C4040 C905E3C5 Pecoceee*#* GOOD AFTERNOON**® INTE® 
000032 09C3D604% D440C9E2 40D9C5C1l C4ES84074 404040F0O F760F1FS& 6OFBF940 4SOF1F24B *RCOMM IS READY : 07-18-85 12.4 


000064 FSF6 . *56 * 
a2~C«:S*«CR:SC«WOOEA 46/0000 =SS—=«*S*~SC*«<C«iGWG~~=«dWSEW3ZE? TOALL. 0000. 00.«~«°~*~*~*~C~«~<~“s*CS*«*SC 
“a2O«S~S*COCWUCCEA we/cOG0=SS*«<*S*<CS*«iRWGG~S~S*«d BST ~—CTOALL. ©0000 «200=2S*é‘<CX SA CO CO 
~a2~C«d;:~S*«:SC*RAQCL =v/0000=SS—S~*~*«<‘C“‘Ci«‘«za ~~ «CEST. «0000«Sd00s”s”s*sti(ié‘iSC SC 
48 «02 U/GOES 44/0000 = «8 ~—=«894199 «1245643261 CNTOL 900 00 | 0 01 00 SO 


000000 FFO2002D O13C5CEC 5C40C706 D6C440C1 C6E3C5D9 D5D6D6D05 5C5C4040 C9IDS5SE3C5 Yecceee*** GOOD AFTERNOON** INTE® 
000032 O9C3IDED4 D440C9E2 4C09C§5C1l C4E8407A 404040FO F760F1F8 6OFBF9I40 4OFIF24B *RCCMM IS READY : C7-18-89 12.% 


000064 F5F6 *56 * 
42 2 O02 eU/CCE4 ../0C00 8 89.199 12-56-3261 CNTO1 0000 00 0 30 00 50 
105 2 02 eV/O0E4 .U/00E4 8 89.199 1265643274 CNTO1 0000 00 0 40 00 50 

000000 155C5C5C 40C706C6 C44CC1C6 E3C50905 D606055C 5C4040C9 D5E3C5D09 C30604D4 *,*¢# GOO0 AFTERNOON** INTERCOMN 

000032 40C9E240 D9OC5C1C4 E8407A40 4040F0F7 60F1F860 F8F94040 FIF24BF5 F61526 * IS READY : 07-18-89 12.560. * 
42 2 O02 .U/CCE4 .-/00CO0 8 89.199 12.5623274 CNTO1 0000 00 0 FA 00 50 
108 0 O02 .U/00E4 ../0000 9 8S.199 12.56.3309 TESTL 0000 ao 0 01 00 50 


0Q0d0Cco FFQ2002D O13C5C5C 5C40C7D6 D6C440C1 C6E3C5D9 05060605 5€5C4040 C9IDS5SE3CS *Feoeeeee #** GOOD AFTERNOON** INTE 
000032 D9C306D4 D440C9IE2 40D09C5C1l C4E8407A 404040FO F760F1F8 60F8F940 40FIF 248 *RCOMM IS READY =: 07-18-89 12.% 
Oco0eSs F5F6 *56 * 


MSGLEN THREAD GPR RSC SSC MMN DATE TIME TIO FLGS USR BMN LOG BLK VAI 
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Figure 63. 


"€9 eansyty 


t6l 


(9 JO ¢€ aBeg) AnoQUTAg Boy, uofAnoexy sepop asa] 


DATE 89.199 TIME 12.56.41 eset TNTERCOAMA LcG DI SPL A ¥ #42 PAGE 3 


MSGLEN THREAD CPR RSC ssc MMN DATE TIME TIO FLGS USR BMN LOG BLK VAT 


42 1 F2 .U/OQ0E4 RA/DO9C1 l2 85.199 12.56.3402 TEST1 0000 00 1 30 00 50 
74 1 O2 .U/CCE4 .U/SOCES l2 89.199 12.5623403 TEST1 0000 00 1 40 00 50 
0c00co 5C5CC5D9 0906D95C 5C404007 C1D9E34C FSF5F5F5 F540D0506 E340C6D06 E405C437 ***ERROR**® PART 55555 NOT FOUND.® 


42 1 F2 .U/CCE4 RA/D9C!1 12 89.199 1225663403 TEST1 0000 00 l FA 00 50 


42 1 O02 RA/09C1l .-/C000 3 89.199 1265663403 TESTI 0000 00 1 30 00 00 

1C4 1 F2 eU/CCE4 RA/09C1 13 89.199 12.56.3408 TEST1 0000 00 l 01 00 50 
000000 FFOZOIF5 F93207C1l D9ES4OF1 F2F3F4F5 4005D6E3 40C6D6E4 D5C440C9 D540E6C1 #2005 9PART 12345 NOT FCUND IN WA® 
000032 C9C5CB8D6 E4E2C540 F3FOFC4O 40404040 40404040 40404040 0000C000 0000 *REHOUSE 300 eoosee * 


42 1 02 RA/CIC1l 42/0CCO 3 89.199 12.56.3408 TESTI 0000 00 1 FA QO 00 


42 1 F2 .U/CCE4 RA/O09C1 13 89.199 126566341C TEST1 0000 00 1 30 00 50 

91 l C2 .eU/COE4 .U/O0E4 13 89.199 12.5€.3411 TESTI 0000 00 1 40 00 5¢ 
ocao00 5C5CC5D9 DID6D95C 5€404007 C109E340 FLF2F3F4 F5400506 E340C6D06 E405C440 S#*ERROR** PART 12345 NOT FOUND * 
000032 C90540E6 C1D9C5C8 D6ES4E2C5 40F3FOFC 37 *IN WAREHOUSE 300. * 


SOS @ OC 2 O22 O22 O28 SS 222228 @S8 HSS SSS OSS BS 2S BSS 2 BSE DELS 2S SS 2S QPS SSS S © O22 OLS 2S OVBSlSE SSS CS 2 2GS SSS @ OLS SBVWVSFVOGESs @@®SVSIOSSHHa oe OGOEIOO®W 


42 1 F2 .U/Q0E4 RA/D9C1 13 89.199 12656-3411 TESTI 0000 00 1 FA 00 50 


2 OP op se eee ee ee ce EE C8 di ome ne Oe ee ee ee ED i a ee ee ee ce ey Se ee ee ee ee ee ee ee ee ep ee ee ce ee Se ey ee ey ee ce ee ee a a ee 


42 l O2 RA/D9C1 .-/0C00 4 69.199 1225623411 TEST1 0000 00 l 30 00 00 

104 1 F2 .U/OQ0E4 RA/DICL 14 89.199 1265623415 TESTL 0000 00 l O01 00 50 
Q000Cco FFOZO1F5 F93Z07C1 DOES4CF1 F2F3F4FS 4005D6E3 40C606E4 D5C44040 40404040 .ee59FePART 12349 NOT FOUND * 
000032 40404C4C 4040404C 40404040 40404040 40404040 40404040 00000000 0000 * eoosce *# 


42 l 02 RA/O9ClL .-/0000 4 85.199 12.56.3415 TESTI 0000 00 l FA 00 00 


42 1 F2 .U/CCE4 RA/09C1 14 89.199 12.56.3415 TEST. 0000 00 1 30 00 50 
74 1 02 U/CCE4 ,U/CCES 14 89.199 12.56.3416 TEST} 0000 00 l 40 00 50 
000000 5C5CC5D9 D9D6D95C 5C404007 C1D9E340 FLF2F3F4 F940D506 E340C6D6 E405C437 *#*ERROR#® PART 12349 NOT FOUND.* 


SEeBeaes OSC 82 O22 22S 4 @ SPSS S PSF SCS SSC GS SS SSS OS S28 BVO SFE VS SVS @ 222 6S OS OS SVS SS @SSVEGVVlVFESS SSW OSS SOS PS@SS OS SS OO es | BFF SHVEFESZ2OSEF2] @O@2eeaedkq@ 


42 1 F2 eU/CCE4 RA/O9C1 14 89.2199 12-56-3416 TESTL 0000 00 1 FA 00 50 


@2E SB O22 @ @O2 @ @ OS @ BSE & OSS 2 O22 SS SOS BSG @FV FF S282 OS SSFVS2 OLS @ SCS OE SE SSS OS © 2B SFSSFE Ss OS SVS BVSlSESVISVPS SS O22 2E8 SS VFFVSFSS BOBS BESTS SO 2 SCFVFV 22222 @2@OOSeOE2 22 


42 1 O02 RA/DICL .e/0C00 5 89.199 1265663416 TEST1 0000 00 l 30 00 00 

192 1 F2 .H/OCC8 RA/SES9C1 15 89.199 12.56.3418 TESTI 0000 00 1 01 00 72 
000000 E2E20908 FOFOFOF1 F0404040 FIF2F3F4 Fl4O0F 161 F440C9D5 40C3C8D9 D604C54C *55RQ00010 12341 1/4 IN CHROME * 
000032 C3C50909 C1E3C5C4 400306C3 024005E4 E3404040 4040404C 40404040 40404040 *CERRATED LOCK NUT * 
000064 40404C4C 40404004 06E94040 SBFOFIFE 4BFLFOFL F64040F1 FOFOOSCS5 E640E 806 * DOZ $616.1616 IlOONEW YO? 
000096 090240C3 C9ESZEBGB 4CDS4BE8 48404040 4QF568FO FSFOGBF5 FOF4SFOF3 61F0F561 RK CITYs NeYe 52050,50403/05/% 
000128 FSF2FS68 FCFSFOCB FSFOF4F1l FO6LFIF1 61F8F200 0000 #825 2050550410/11/82ec6 . 


42 1 O02 RA/OGCL e«e/0C00 5 89.199 12.56.3418 TESTI 0co0 00 1 FA 00 00 


42 1 F2 .eH/CCCS8 RA/SOICI 15 89.199 12.56.3418 TEST1 0000 00 1 30 00 72 


MSGLEN THREAD QPR RSC SSC MMN DATE TIME TIO FLGS USR BMN LOG BLK VAI 
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epoyw 3ASel ut Zutqjsey waqsAsqns 
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Appendix A 


ASSEMBLER LANGUAGE JCL PROCEDURES 


The following JCL procedures, which use Assembler H, are supplied 
on the Intercomm release library, SYMREL. Check with your System 
Manager before using them to ensure they reside on your installation’s 
system procedure library (SYS1.PROCLIB) and to verify parameters to 
code. When appropriate, SYSLIB references Intercomm libraries. 


ASMPC: Assemble BAL source code 

Example: // EXEC ASMPC ,Q=TEST , NAME=BALPROG 

ASMPCL: Assemble BAL source code and linkedit it to produce a load 
module. (The linkedit step, PARM overrides AMODE=31 and 
RMODE=ANY, cause the program to be loaded above the l6meg 
line). 

Example: // EXEC ASMPCL,Q=TEST , NAME=BALPROG , LMOD=BALPROG, 
// PARM. LKED=' LIST, XREF, LET ,NCAL, AMODE=31 , RMODE=ANY ’ 


IEBUPDTE step, followed by Assembly of updated source 
code. Add: 

//LIB.SYSIN to specify IEBUPDTE control and change cards. 
// EXEC LIBEASM,Q=TEST , NAME=BALPROG 


LIBELINK: IEBUPDTE step, followed by same JCL as ASMPCL. 


Note: LKED override parms for 31 Amode, as in ASMPCL, may be 
used. Add //LIB.SYSIN statement to specify IEBUPDTE 
input. 


Figure A-l. Intercomm-supplied Assembler JCL Procedures 


Refer to the Intercomm Qperating Reference Manual for further 
details on JCL parameter requirements, and other BAL procedures for 
Assembler F. 


For Assembler Language programs eligible for loading above the 
l6meg line under MVS/XA or ESA, add the following to procedures with a 
linkedit step: 


//LKED.SYSIN DD * 
INCLUDE SYSLIB(CINTLOAD) 
ENTRY user -program-name 


For those to be dynamically loaded below the l6meg line, or if executing 
under MVS/370, an include for INTLOAD will save dynamic linkedit time at 
Intercomm Startup for direct calls to system routines, and for system 
macro-generated calls. 
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Appendix B 


DSECTS FOR ASSEMBLER LANGUAGE PROGRAMS 


The following lists members in the Intercomm SYMREL source 
library which contain source statement code for Intercomm Dsects which 
can be inserted in a BAL program simply by coding COPY member-name at 
the desired source line, or by coding the listed macro. Generating 
Dsects for the MCB and EXTDSCT areas are listed for debugging purposes 
only. SYMREL must be named in the DD statement concatenation for the 
SYSLIB data set for assemblies (automatic if Intercomm-supplied 
Assembler procedures used). For the Dsect label, the word user means 
the programmer must choose a name and prefix the COPY or macro 
statement with a labeled DSECT statement. 


NOTE: except for the user-generated MMU Symbolic Map area, and 
selected Message Header fields (see Figure 7), none of 
the other areas (field values, bit settings, etc.) may be 
changed by a user program during Intercomm execution. 
System commands are available to change some tables 
dynamically as described in System Control Commands. 
Dsects for all table areas are listed in an appendix of 


the Operating Reference Manual. 
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Generated by Dsect label 

COPY MSGHDRC 

MSGHDR macro user 
LINKAGE macro MSGHEAD 
Parameter LINKAGE macro PARMLIST 3-word parameter list 
List PARMLIST macro user passed to subsystem 
SCT LINKAGE macro SCTLIST SYCTTBL macro-generated 
entry COPY SCTLISTC SCTLIST fields in SCT 
SCT automatic - SCTEXTLT SYCTTBL (SCT) extensio 
extension after SCT entry for dynamic load 

SPA LINKAGE macro SPALIST SPA Csect fields 
SPALIST macro user followed by USERSPA 

(if any) 
automatic - SPAEXT SPAEXT (SPA extension) 
after SPA, Csect fields 
USERSPA 
COPY user MMU user-generated 
(MMU SYMGEN symbolic map fields 
JCL proc) 
COPY MCBDSECT MMU mapping control 
block (MCB) fields 
IXFDSCTA macro File Handler EXTDSCT 
fields 


Description 


Message Header fields 
(see Figure /7) 


Message 
Header 


user 


EXTDSCT 
area 


Figure B-1 Intercomm Dsects for Assembler Programs 
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PAGES 201-204 INTENTIONALLY MISSING 
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Appendix C 


INTERCOMM TABLE SUMMARY 


Basic tables are included in the Intercomm release library 
(SYMREL) and must be modified (added to) for each installation. An 
asterisk (*) indicates optional tables which may be _ generated 
individually at each installation according to application program 
requirements. A complete list is provided in an Appendix of the 


Operating Reference Manual. 


TABLE or 
CSECT MODREL 
Name Description Created by Member Name 
BROADCST *Output Broadcast Table | BCGROUP macro PMIBROAD 
BTAMSCTS Front End Queue Table SYCTTBL macro BTAMSCTS 
(BTAM/TCAM/GFE only) 
BTIVRBTB BTVERB macro BTVRBTB 
(User-name) | Front End Network LINEGRP, BLINE FENETWRK 
Configuration Table BTERM macros, etc.| (BTSAMP) 
VCT, LUNIT, (VTSAMP ) 
LCOMP macros, etc. 
CHNGTB *Change Table for DC's None 
Change/Display Utilities 
File *File Descriptions Data | FDHDR, FDETL None 
Description | Set (DESO00); generated | macros 
Records by file load utility 
(DESnnnnn) PMIEXLD (for Change/ 
Display Utility) 
IXFDSCTn File Handler Data Set IXFDSCTA macro IXFDSCT1 
Control Table (50 DDs) 
IXFDSCT2 
(100 DDs) 
| IXFDSCT3 
(200 DDs) 


Figure C-1. Table Names and Associated Macro Instructions (Page 1 of 2) 
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Appendix G Intercomm Table Summary 


SYMREL and 
MODREL 


Description 
*Display Utility Key 
Transformation Routing Table 


*Output Utility Alternate 
Format Table 


PMIRCNTB 


REPORT, LINE 
ITEM macros 


*Output Utility Company/ 
Report/Terminal Table 


ee weee weaerwew w= w@ @ @ = = eeeeweF w@ @ wee == w 


*Display Utility Symbol Edit 
Pattern Table 


eweeweeeee#z2e = 2 @ ew eweeeewsew w= wZ ww eweewerweteeeweeeeee weee®# wes = = =wwewerweweweew’e= fw FB ZT @ = = = =sweewewewewwvww ew 2 = = = 


VERBTBL *Edit Control Table 


VERBGEN, VERB, PMIVERBS 
PARM, PMIELIN 
macros 


Figure C-1. Table Names and Associated Macro Instructions (Page 2 of 2) 
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Change/Display Utility CHNGTB 
File Description Records 


KEYTABLE 
PMIFILET 


PADDTBLE 
PMIFILET 
PMIVERBS 
PMIDEVTB 
PMISTATB 
IXFDSCTn 
FAR statements 
BTIVRBTB 
Front End Network Table 
BTAMSCTS 


PMIDEVTB 
PMISTATB 
User-coded Maps 
REENTSBS 
INTSPA 

INTSCT 

BROADCST 
PMIALTRP 
PMIDEVTB 
PMIFILET 
PMIRCNTB 
PMIRPTAB 
PMISTATB 
REPTAPE 

RPTnnnnn (user-coded OFTs) 


PAGETBL 


Output Utility 


Page Facility 


Figure C-2. Components and Associated Table Names 
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Appendix D 


SPA AND SPAEXT FIELD NAMES FOR ROUTINE ENTRY POINTS 


The following tables list the names of fields in the Intercomm 
SPA and SPAEXT Csects of the System Parameter List which are labels of 
Vcons containing service routine entry point names. The field SPAEXTAD 
in the SPA Csect contains the address of the SPAEXT Csect. 
Addressability to SPAEXT must be established (see Chapter 9) before 
referencing any field whose label begins with the letters SEX (see also 
the SPAEXT parameters of the LINKAGE and SUBLINK macros in Basic System 
Macros). Entry points for macro-called routines are listed under the 
related macro description in the Macros manual. Table addresses and 
other fields of interest to systems programmers writing user exits may 
be found by studying the SPALIST macro-generated Dsect listing. 


D.1 FIELDS IN THE SPA 


SPAPEDT DC V(EDITCTRL) Pointer to Edit routine 

SPAPMCR DC V(MSGCOL) Pointer to Message Collection 
SPAFECRL DC V (FECMRLSE) Address of FECM RLSE routine 
SPAFINDB DC V(PMIFINDB) Ptr to routine to find Item Code 
SPAFECFB DC V (FECMFDBK) Address of FECM FDBK routine 
SPADLTDB DCG V( PMIDLTDB) Ptr to routine to Add/Delete field 
SPASELCT DC V( SELECT) File Handler SELECT routine 
SPARELES DC V (RELEASE) File Handler RELEASE routine 
SPAWRITE DC V(WRITE) File Handler WRITE routine 

SPAREAD DC V(READ) File Handler READ routine 

SPAWHOIT DC VC IJKWHOIT) Csect, etc. name lookup routine 
SPACONVR DC V (CONVERSE) Conversational Enviroment saving 
SPASORT DC VC INTSORT) In-core Table Sort routine (Rel 10) 
SPALOGP DC V(LOGPUT) Logging routine 
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D.2 FIELDS IN THE SPAEXT 


SEXGET 
SEXPUT 
SEXLOCAT 
SEXRELEX 
SEXGETV 
SEXPUTV 
SEXBINSH 
SEXDELAY 
SEXPRINT 
SEXSECUS 
SEXFESND 
SEXFECDQ 
SEXCONVR 
SEXDBINT 
SEXPAGE 
SEXDVASN 
SEXGETSG 
SEXBSRC3 
SEXDQBLD 


V(GET) 
V(PUT) 
V(LOCATE) 
V(RELEX) 
V(GETV) 
V(PUTV) 
V(BINSRCH) 
V(IJKDELAY) 
V(IJKPRINT) 
V(SECUSER) 
V(FESEND) 
V(FECMDDQ) 
V (CONVERSE) 
V(DBINT) 

V (PAGE) 
V(DVASN) 
V(GETSEG) 
V(BINSRCH3) 
V(QBUILD) 
V(QOPEN) 
V(QCLOSE) 
V(QREAD) 
V(QWRITE) 
V(QREADX) 
V(QWRITEX) 
V(IJKTRACE) 
V(ALLOCATE) 
V(ACCESS) 
V(INTFETCH) 
V(INTSTORE) 
V(INTUNSTO) 
V(MAPIN) 
V(MAPOUT) 
V(MAPEND ) 
V(MAPURGE) 
V(MAPCLR) 

V (MAPFREE) 
V(BINSRCH2) 
V(FESENDC) 


SPA and SPAEXT Field Names 
for Routine Entry Points 


File Handler GET entry 

File Handler PUT entry 

File Handler LOCATE entry 

File Handler RELEX entry 

VSAM GET entry point 

VSAM PUT/ERASE entry point 

Binary search - halfword index 
Dispatcher - timed DELAY routine 
Line Print Routine (Rel 10 only) 
ESS Operator-id Checking (Rel 10) 
FESEND entry point 

Address of FECM DDQ routine 
Conversational Environment saving 
Data Base interface 

Page Facility processing 

Output term. control-segmented msgs 
Input message segment retrieval 
Binary search - fullword index 

DDQ Queue Build entry point 

DDQ Queue Open entry point 

DDQ Queue Close entry point 

DDQ Queue Read (normal) entry point 
DDQ Queue Write (normal) entry point 
DDQ Queue Read (update) entry point 
DDQ Queue Write (update) entry point . 
WQE Trace dump processing wail 
ALLOCATE routine (DFA) 

ACCESS routine (DFA) 

FETCH (Store/Fetch) 
STORE (Store/Fetch) 
UNSTORE (delete) (Store/Fetch) 

MMU MAPIN entry point 

MMU MAPOUT entry point 

MMU MAPEND entry point 

MMU MAPURGE entry point 

MMU MAPCLR entry point 

MMU MAPFREE entry point 

Table Binary Search entry 
FESEND-Copy message entry 
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PAGES 211-214 INTENTIONALLY MISSING 
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Appendix E 
NONREENTRANT SUBSYSTEMS 
E.1 INTRODUCTION 


Nonreentrant subsystems do not use a dynamic save/work area. The 
LINKAGE and RINLINK macros are not used. The programmer must save and 
restore the Monitor's registers using the IBM SAVE and RETURN macros, 
set base registers, chain a local save area, and generate Dsects as 
appropriate. At entry, the same parameter list is passed as to a 
reentrant BAL subsystem. The user must initialize registers (input 
message, SPA) from the parameter list, and define USING statements for 
the associated Dsects. As illustrated in Figure E-1, both constant and 
variable data areas are defined in the program. Therefore, nonreentrant 
subsystems are always single-threaded; each input message is processed 
to completion and the subsystem returns to the Monitor before a new 
message can be processed by the subsystem. On the SYCTTBL macro for the 
subsystem, MNCL=l1 and LANG=NBAL must be coded. Obviously, if messages 
might be input to the subsystem from more than one terminal 
concurrently, response time for each message queued after the first will 
be increasingly slower. Thus, it is recommended that Assembler Language 
subsystems always be coded as reentrant. 


To call a user subroutine, the MODCNTRL macro may not be used. 
Instead, the subsystem calls the routine directly, and the user 
subroutines must be resident in the Intercomm load module or in the same 
overlay segment as the subsystem; they are not defined in REENTSBS. 
CONVERSE may not be called from a nonreentrant subsystem. The Intercomm 
environment for a nonreentrant subsystem is illustrated in Figure E-2. 


The STORAGE macro must be used to acquire an area for a message 
passed to MSGCOL. A hard-coded area in the program may be used if 
FESENDC is called for an output terminal message. Giving up control to 
the Monitor within the program via the INTENQ, DISPATCH, INTWAIT or 
SUBTASK macros is not recommended. Before returning control to the 
Monitor, a STORFREE of the input message is still required. 


Nonreentrant programs are not eligible for loading above the l6meg 
line under XA. 
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SUBSYSYY CSECT 
REGS 

*SUBSYSTEM ENTRY 
SAVE 


set base, parms, chain save areas 


*MESSAGE PROCESSING LOGIC 


*GET CORE FOR OUTPUT MESSAGE 
STORAGE ...,RENT=NO 


Build Output Message 


*PASS THE MESSAGE TO THE FRONT END VIA FESEND, OR 
*QUEUE THE OUTPUT MSG VIA MSGCOL 
CALL ...,VL,MF=(E, PARMSAVE) 


*FREE THE INPUT MESSAGE 
STORFREE 


*SUBSYSTEM EXIT 


L R13 ,4(R13) restore caller's R13 
RETURN ...,RC=(r) register r contains return code 
* 
REGSAVE DS 18F 
COREADDR DS F 
PARMSAVE DS 5F 
SUBSYSWK DS 


define subsystem constants and variables 


* 

INMSG DSECT 

INHDR DS CL42 
INTEXT DS 


define input text format 


INLEN EQU *-INHDR 
* 
OUTMSG DSECT 
OUTHDR ODS OCLA2 

COPY MSGHDRC 
OUTTEXT DS 

: define output text format 

OUTLEN EQU *-QUTHDR 
SUBSYSYY CSECT 

END 

Figure E-1. Nonreentrant Assembler Subsystem Structure 
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SYSTEM 
INTERCOMM PARAMETER 
SYSTEM AREA 


SUBSYSTEM 


FILE CONTROL 
LANGUAGE HANDLER 
INTERFACE B 


SUBSYSTEMS 
SUBSYSTEM BB 


BAL SUBSYSTEM AA 


PARMLIST 
POINTERS 
> ae IN-MSG CONSTANT ITEMS SAVE AREA 


€-G) scr | INDEPENDENT ITEMS 


RECORD 
AREAS 


INTERCOMM DYNAMIC POOL STORAGE MVS SUBPOOLS 


OUTPUT 
MESSAGE 
AREA 
O.S. 
ACCESS METHODS 


AA INPUT 
MESSAGE 


Figure E-2. Nonreentrant Application Program Environment 
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PAGES 218-220 INTENTIONALLY MISSING 
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Page 
ACCESS function (DFA) 110.3,210 
ADABAS data base 15,52 
ALLOCATE function (DFA) 110.3,210 
Alternate Format Table 206-207 
Alternate Index (VSAM) 71 
Alternate Path processing (VSAM) 71 
AMODE linkedit parameter 46.2,197 
AMP parameter (VSAM JCL) 67,74 


Application processing functions 7 
Application Programs. See Subsystems. 


ASMLOGCH copy member 123 
ASMPC procedure 197 
ASMPCL procedure 197 
AUTOLOK feature 94 
Back End--defined 11 
Back End Device Table. See Device 
Table. 
Back End Station Table. See 
Station Table. 
Backout-on-the-Fly 6,34 
Batch execution 1,3,30 
Batch Report Table 206-207 
BCGROUP macro 205 
BDAM access method 
--DCB 64 
--DD statement parameters 52 
--and exclusive control 57 
--and File Handler Option Codes 65 
--and File Handler Parameters 54 
--and File Handler return codes 66 
--sample inquiry subsystem 123 
--service routines 51,64 
BDW. See Block Descriptor Word. 
Binary table search 104 
BINSRCH 104-105,210 
BINSRCH2 104-105,210 
BINSRCH3 104-105, 210 
BISAM access method 
--DD statement parameters 52 
--and exclusive control 57 
--and ISAM/VSAM compatibility 74 
--processing 62 
--return codes 63 
--service routines 51,62 
BITSECT table 46.3 
BLDL parameter (SUBMODS macro) 46.3 
BLDL parameter (SYCTTBL macro) 46.2 
BLHOT module 29 
BLINE macro 205 
Block Descriptor Word 61 


INDEX 
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Page 
Broadcast Group 20,75 
Broadcast Table 205,207 
BROADCST. See Broadcast Table. 
BSAM access method 51-52 ,57,60 
BTAM 11 
--simulator 123 ,129-131 
BTAMSCTS. See Front End Queue 
Table. 
BTAMSIM module 131 
BTERM macro 205 
BTSAMP table 205 
BIVERB macro 
--and BTVRBTB 17,18 
--and editing 35 
--and priority 21 
--and sample subsystem 130,132,168 
--and subsystem codes 18 
--table summary 205 
BIVRBTB. See Front End Verb Table. 
CALL macro 10 
--and MVS/XA loading 46.2 
CALLIF macro 111 
CALLOVLY macro 46.2,111 
Cancelled messages 34,46.1 
CATCH macro 113,114,120 
Change/Display Utility 
--described 16 
--and formatting required, 
fixed text messages 76,167 
--and message switching 46.1 
--and sample subsystem 167 
--tables used by 207 
Change Table 167,180,205, 207 
Checkpointing 6,28 
CHNGTB. See Change Table. 
Closing files DL 52597 
Commands (Intercomm) 16 
Company/Report/Terminal 
Table 206-207 
Conversational subsystem. See 
Subsystems, conversational. 
Conversational time-out 
(Front End) and FESEND 99 
CONVERSE 
--automatic time-out 90-91 
--calling format 90 
--and conversation implementa- 
tion options 81 
--described 88 
--and LINKAGE macro 90-91 


Page 


--and nonreentrant subsystems 215 
--return codes 91 


--and SPA VCONs 209 
--and SPAEXT VCONs 210 
--subsystem design 90 
--subsystem logic using 89 
CREATEGF utility 64 
CREATSIM utility 129-130 
--JCL for 134-135 
Data Base interface 52,110.3 
Data field search routines 105 


Data Set Control Table 17 
Data Set Name Sharing (VSAM) 
Data strings 

Dataspeed 40 terminal 21 


DBINT function 110.3,210 
DPMS support 15,24,34,110.3 
DDNFIND macro lll 


DDQ. See Dynamic Data Queuing. 
Debugging program problems 129 
DESOOQ data set 167,205 


Device control characters 49 
DEVICE macro 206 
Device Table 17,98 ,206-207 
DFA. See Dynamic File Allocation. 

DISPATCH macro 46.2,113-119,215 
Dispatcher 12 


--and IJKDELAY 110,110.1 
--and IJKPRINT 110 
--and TJKTRACE 110,110.1 
DL/I data base 15,52 


DSCT. See Data Set Control Table. 
Dsects 39-40 ,44,83,215 
--generation of 199-200 


DSN option. See Data Set Name Sharing. 


DVASN service routine 76,109,210 

Dumps 129 

Dynamic Data Queuing 
--and conversational subsystem 81 
--described 15 
--and Front End Data Queuing 100 
--and Message Mapping Utilities 47 
--and segmented input messages 22,30 
--and SPAEXT VCONs 210 
--subroutine entry names 110.3,210 
--types of queues 86 
--use of 30,86-87 


Dynamic File Allocation 15,30,110.3,210 


Dynamic file backout 6,34 
Dynamic loaded subsystems 18,131,168 
--and dynamic linkedit 30,46.2 
--and SCT Extension 200 
DYNLLOAD module 46.3 
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ECT. See Edit Control Table. 

EDIT. See Edit Utility. 

EDIT parameter (BIVERB macro) 35,37 
Edit Control Table 


--associated components 207 
--described 49 
--macros 206 
--and message flow using EDIT 
and OUTPUT 24 
--and required fields 50 
--and subsystem testing 123,167 
EDITCTRL edit entry 49,209 
Edit subroutines 49 
Edit Utility 
--concepts 14,49 
--and CONVERSE 91 
--function 14 
--message flow using 24-25 
--and message switching 46.1 


--and MSGHUSR field 21 


--processing results 49-50 
--and sample subsystem 123,167 
--and segmented input 108 
--subsystem logic using 37-38 
--and subsystem testing 123,167,180 
--tables used by 17,207 
--and terminal tables 17 
--using 49-50 
--and verb message 
identifier (MSGHVMI) 35,38,46.1 
Entry sequenced data sets 54,67 
Error messages 
--and calls to service routines 35 
--and conversational subsystems 79 
--and debugging 129 
--and Edit Utility 50 
ESA (IBM). See MVS/XA. 
ESDS. See Entry sequenced 


data sets. 
ESS. See Extended Security System. 
Exclusive Control 

--and File Handler Control 


Word 53 
--for non-VSAM files 57-59 
--processing (file/record) 58 
--releasing (file/record) 59 
--and resource control 113 
--and Store/Fetch 85 
--for VSAM files 70 

EXEC statement parameter 131,168 
EXMVE macro 111 
EXSS macro 111 
EXTDSCT. See External DSCT. 
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EXTRT macro 111 
Extended Security System 15,29,112 
External DSCT 53-54,56-57,59 
--Dsect generation 199-200 
FAR. See File Attribute Record. 
FDETL macro 205 
FDHDR macro 205 
FDR. See File Description Records. 
FECM. 98 
See Front End Control Messages. 
FECMDDQ. See Front End Data 
Queuing. 
FECMFBK. See Front End Feedback 
Messages. 
FECMRLSE. See Front End Queue 
Release. 
Feedback codes, VSAM 70,73 
FENETWRK table 136,205 
FESEND 
--calling format 98 
--described 98-99 
--and conversational time-out 99 
--and FESENDC entry point 94,98 
--and Front End Control 
Messages 100 
--and Front End Feedback 
Messages 101 
--and Front End Queue 
Release 99,103 
--function 14,35 
--and INTERLOG 27-29 
--and message flow using EDIT 
and OUTPUT 24-25 
--and message flow using MMU 22-23 
--and message header altering 21 
--and Message Mapping 
Utilities 22-23,39,47 
--and option codes 99 
--and Output Utility 24-25,75 
--return codes 99 
--and SPAEXT VCONs 210 
--and storage control 42 
--and subsystem coding 39 
--and subsystem logic using 
EDIT and OUTPUT 38 
--and subsystem logic using MMU 36 
--and VTAM 99,103 
FESENDC entry point 94 ,98-99,210,215 
FETCH function 84-85 


FHCW. 
Word. 


See File Handler Control 
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FILE command 

File Attribute 
Record 17,51,56,61,62,67,71,207 

File Description Records 76,16/7,205,207 


56,57 


--illustrated 182 
File Handler 
--access methods supported 52 
--and batch execution 30 
--and closing a file 52,57 
--described 12 ,51-52 
--and direct access files 64-66 
--error checking 55 
--exclusive control 
--non-VSAM files 57-59 
--VSAM files 59 | 
--peneral concepts 51-52 
--and indexed sequential 
files 62,63 
--and ISAM/VSAM compatibility 74 
--and message flow using EDIT 
and OUTPUT 24-25 © 
--and message flow using MMU 22-23 
--and MVS/XA 46.2,56 
--above 16-meg line restrictions 54° 
--parameters 3 54 
--return codes 55-56,59-60,63,66,73 © 
--and sample inquiry subsystem 123, 
--SELECT and RELEASE functions 56 
--and sequential access . 
files 60-61 
--service routines 51,53-55,215 
--and SPA VCONs 209 
--and SPAEXT VCONs 210 
--subsystem processing 52-53 
--tables used 205,207 
--and undefined record format 61 
--and variable length records 61 
--and VSAM 59 ,67-73 
File Handler Control Word 
--and closing a file 57 
--described 53-54 
--and direct access files 64-65 
--and exclusive control 57 
--and indexed sequential files 62 
--and ISAM/VSAM compatibility 74 
--return codes 55 
--and undefined records 61 
--and VSAM files 69-71 
File Handler Data Set Control 
Table 17,205 
File Recovery feature 6,51,97 
File Table 206-207 
Flushed messages 29 


Page 
Format Description Record. 
See File Description Records. 
Front End 
--defined 11 
--and system commands 98 
--and TP Queuing Interface 12 
Front End Control Messages 100-103 
--and FESEND 98 


Front End Data Queuing 30,100-101,210 
Front End Feedback Messages 100-102,209 
Front End Network Configuracion 


Table 17,205,207 
Front End Queue Release 99,100,103,209 
Front End Queue Table 205 , 207 


Front End Verb Table (BTVRBTB) 
--and AUVTOLOK 94 


--creation of 17,205,207 
--and CONVERSE 90-91 
--and editing 37,49 
--f£unction 17-18 
--and message processing (VMI) 35 


--and USRBTVRB 18,130,132,168 


GENFTBLE macro 206 
GET service routine 
--calling format 60,62 
--and exclusive control 57-59 
- -function 51 
--and indexed sequential tiles 62 
--and ISAM/VSAM compatibilty 70,74 
--and sequential access 
files 60-61 
--and SPAEXT VCONs 210 
--and subsystem processing 52 
GETDATE macro 111 
GETSEG service routine 108 ,210 
GETSPA macro 111 
GETV service routine 
--calling format 67-68 ,72 
--and exclusive control 70 
--and FHCW reason codes 70 
--function 51 
--and SPAEXT VCONs 210 
--and subsystem processing 52 
--and VSAM files 67-68 
--and VSAM processing options 69-71 
HEXCON macro 110.3,111 
HPRTY parameter (BIVERB macro) 21 
IAM access method 52,54 


IBM 2740 Terminal 21 
IBM 3270 Display Station 21,49,131 
--and simulation testing 130 


224 


Page 
ICOMLINK macro 136,185 
IDMS data base 15,52 
IJKDELAY service routine 110.1,210 
IJKPRINT service routine 110,210 
IJKTRACE service routine 110.1,210 
IJKWHOIT service routine 110.3,209 
Indicative dumps 129 
INTDEQ macro 113,115,121 


INTENQ macro 
INTERLOG file 
26,28-29,97,161-166,191-196 


113,115,121,215 


--JCL for 138 
INTFETCH function 110.3,210 
INTLOAD 

--and mode switching 46.2 

--and MVS/XA 46.3,110.4,197 
INTPOST macro 113,115,197 
INTSCT module 18, 206 

--and USRSCTS 130,132,167,180 
INTSORT Facility 110.2,209 
INTSPA module 82 , 206 
INTSTORE function 110.3,210 
INTTIME macro 111 
INTUNSTO function 110.3,210 


INTWAIT macro 113,115,117-118,215 
ISAM (see also BISAM and QISAM) 


--access by File Handler 52 
--File Handler processing 62 
--File Handler return codes 63 
--File Handler service routine 
parameters 54 
--and VSAM 67,70,74 
ITEM macro 206 
IXFCHKPT module 28 
IXFDSCTA macro 200,205 
IXFDSCT1/2/3/n 205,207 
IXFLOG (File Recovery logging) 28 
JCL 
--Assembler procedures 197 
--CREATSIM utility 134-135 
--DD statement for File 
Handler 51-52 
--for direct access files 64-66 
--for indexed sequential files 62 
--for ISAM/VSAM compatibility 74 
--sample simulation Mode 136-139 
--sample Test Mode 185-187 
--for VSAM files 67,187 
JOBCAT DD statement (VSAM) 131 


Journaling. See Logging. 
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Key Table 206-207 
Key sequenced data sets 54,67 
KEYCREAT utility 64 


KSDS. See Key sequenced data sets. 


LANG parameter (SYCTTBL macro) 


18 ,46.2,215 
LAYOUT macro 110.3,111 
LCOMP macro 205 
LIBEASM procedure 197 
LIBELINK procedure 132,180,197 
LIMCT parameter (JCL) 52,64 
LINE macro 206 
Line control 6-7 
LINEGRP macro 205 
LINKAGE macro 
--and coding techniques 42-43 
--and CONVERSE 90-91 
--and Dsects 39-40, 83,200 
--and dynamic storage 40 
--and MVS/XA 46.2,110.4 
--restrictions 46.3 
--and nonreentrant subsystems 215 
--and output messages 42 
--and subsystem linkage 38 
Linkedit 130,136-137,168,185-186,197 


--and MVS/XA 46.2-46.3,197 
LKEDT procedure 137,186 
LNAME parameter (SUBMODS macro) 46.3 


LOAD command 30 
LOADNAM parameter (SYCTTBL macro) 
18 ,46.2 
LOCATE entry point 210 
LOCK command 93-94 
Log Analysis utility 21,26 
Log codes 26-29 ,46.1,97 
Logging. See INTERLOG file. 
LOGCHARS table 207 
LOGPROC module 28 
LOGPRINT utility 21,26 
--sample JCL for 138 
LOGPUT module 
--calling format 97 
--function 14 
--and INTERLOG entries 28-29 
--and SPA VCONs 209 
--and user entries on 
INTERLOG 26,97 
LOGTROUT table 97 
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LSR (pools) option (VSAM) 67,71 
LTORG statement 45 
LUNIT macro 205 
Macros (Intercomm) a4 
--for Dsects 199-200 
--listed 111-113 
--for Tables 205-206 
--and MVS/XA loading 46.2-46.3 
MANAGER module 46.3 
Map Control Block 199-200 
MAPCLR function 110.3,210 
MAPEND function 34,36,48,102,110.3,210 
MAPFREE function 110.3,210 


MAPIN function 36,42,48,110.3, 210- 
MAPOUT function 36 ,48,110.3,210 
MAPURGE function 110.3,210 
MCB. See Map Control Block. 

Message Collection 


--calling format 96 
--function 14 
--and INTERLOG 28-29 
--log codes 27 
--and message flow using 

EDIT and OUTPUT 24-25: 
--and message flow using MMU 22-23 
--and message switching 96 
--and MSGHMMN 20 
--and nonreentrant subsystems 215 
--and MSGHUSR 21 
--return codes 34,96 
--and SPA VCONs 209 
--and storage control 42 

Message header 

--changing 35 
--and CONVERSE 90 . 
--described 19-21 . 
--Dsect generation 40,200 
--and Message Collection 96 
--and message flow using EDIT - 

and OUTPUT 24-25 
--and message flow using MMU 22-23 
--and message processing logic 35 
--and message routing 18 
--and output messages 35,77 
--specifications for the Output 

Utility 77. 
--and subsystem structure 31,44 
--and Test Mode input 183 


--and user log entries 97 
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Message Mapping Utilities 

--described 14,47 
--and Dynamic Data Queuing 39 

--and Front End Data 
Queuing 100-101 
--function 14 
--and log codes 27 
--maps for sample subsystem 133 
--message flow using 22-23 
--and messages to Front End 39 ,98 
--and MSGHQPR 22 
--and MSGHVMI 44 
--and MVS/XA 46.2 
--and Page Facility 39 
--processing 22,30,47-48 

--and sample inauiry 
subsystem 123,130 
--service routines 110.3,210 
--and SPAEXT VCONs 210 
--and subsystem logic 35-36 ,48 
--and subsystem testing 130,131 
--symbolic maps 47,200 
--tables used by 17,207 


Message Processing 7 


Message Processing Control 6-7 
Message switching 46.1,96 
MMU. See Message Mapping Utilities. 

MMUCG command 130,141 
MMUVTBL table 207 


MNCL parameter (SYCTTBL 
macro) 
MODCNTRL macro 


19,131,168,215 


--ACTION parameter 46.3 
--and MVS/XA loading 46.3,116 
--and nonreentrant subsystems 215 
--and system control 113,116 
- -usage 121 
--and XASWITCH macro 46.3,116 
Model 204 data base 15,52 
Monitor Control Functions 7 
MRINTER module 28 
MRQOMNGR module 28-29 
MSGAC module 29 
MSGCOL. See Message Collection. 
MSGHADDR field 20 
MSGHBLK field 20 
MSGHBMN field 20,26,183 
MSGHCON field 20 
MSGHDAT field 20,26,97 
MSGHDR Dsect 40,200 
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MSGHDR macro 111,200 
MSGHDRC copy member 44,200 
MSGHFLGS field 20 
MSGHLEN field 
--described 20 
--and Front End Control 
Messages 102-103 
--and output messages 44 
--and STORFREE macro 41 
--and user log entries 97 
MSGHLOG field 20,26,97 
MSGHMMN field 20,26 
MSGHQPR field 20 
- -described 22 
--and segmented input 76,98,108 
MSGHRETN field 20,34 
MSGHRSC field 
--and assigning verb to terminal 94 
--described 20 
--and Message Collection 96 
--and message routing 18,35 
--and message switching 96 
--and output messages 44,77 
--and subsystem logic using 
EDIT and OUTPUT 37 
--and Test Mode 183 
MSGHRSCH field 
--and assigning verb to 
terminal 94 
--described 20 
--and Message Collection 96 
--and message routing 18,35 
--and message switching 96 
--and output messages 44,77 
--and subsystem logic using 
EDIT and OUTPUT 37 
--and Test Mode 183 
MSGHSSC field 20,44 
MSGHSSCH field 20,44 
MSGHTID field 
--described 20 
--and FESEND 98-99 
--and Front End Data Queuing 101 
--and Front End Queue Release 103 
--and message switching 46.1 
--and Output Utility 75 
--and segmented output 109 
--and Store/Fetch facility 84 
--and subsystem coding 44 
--and Test Mode 183 
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MSGHTIM field 20,26,97 
MSGHUSR field 20,21 
MSGHVMI field 
--described 20,22 
--and Edit Utility 35,38,41 
--and FESEND 21,98 
--and Front End Control 
Messages 100 
--and Front End data queuing 100 
--and input messages 35 
--and message processing 35,41 
--and message switching 46.1 
--and output messages 44,75-/7 
--and subsystem logic using 
EDIT and OUTPUT 37 
--and Test Mode 183 
--values 35 
Multiregion System 
--and batch interface 30 
--and testing 129 
Multithread processing 
--described 4-5 
--and exclusive control 57 
--and message flow using MMU 22 
--and reentrant subsystems 16 
--and subsystem testing 131,168 
MVS /XA 
--and CONVERSE 90 
--extended storage loading 
requirements 46.2-46.3 
--and FECMDDQ Lol 
--and File Handler calls 94-57 
--and INTLOAD 46.2,110.4,197 
--and MODCNTRL macro 46.2,116 
--and nonreentrant programs 215 
--and subroutines interfaces 46.2 
--and subsystem coding 


requirements and restrictions 46.3 


--and subsystem loading 45 

--and SUBTASK macro 46.2,117 

--and XASWITCH macro 46.3,112,116 
Network Table 17,205,207 
Nonreentrant subsystems 16,215-217 
OFT. See Output Format Table. 
OPEN option 51 
Opening files 51-52 
OTQUEUE user exit (VTAM) 21 
Output Format Number 168 
Output Format Table 

--associated components 207 
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--creation of 206 
--described 76 
--and message flow using 
EDIT and OUTPUT 24 
--and subsystem testing 168 ,181-182 
Output Utility 
--and CONVERSE 90 
--described 16,75 
--and Front End feedback 
messages 101 
--function 14 
--and INTERLOG 26-27 
--message flow using 24-25 
--message header 
specifications for 77 
--and message switching 30,46.1 
--and MSGHQPR 22 
--and MSGHVMI 41,77 
- - processing 24 ,75-76 
--and sample inquiry 
subsystem 123,167 
--and segmented output 109 
--subsystem logic using 37-38 , 
--and subsystem testing 168 
--tables used by 17,207. 
Pad character table 206-207 | 
PADD macro 206 . 
PADDTBLE. See Pad character table. © 
PAGE entry point ~ 210 
Page Facility 
15-16 ,47,110.3,206, 207,210 
PAGETBL macro 206 
PAGETBL table 206-207 
PARM macro 206 
PARMLIST Dsect 40,200 
PARMLIST macro 200 
PASS macro 113,116 
PATRN macro 206 . 
Pattern Table 206-207 | 
PMIALTRN macro 206 
PMIALTRP. See Alternate Format 
Table. 
PMIBROAD. See Broadcast Table. 
PMICANC. See USRCANC. 
PMIDEVTB. See Device Table. 
PMIDLTDB search routine 105-106,209 . 
PMIELIN macro 206 — 
PMIDVASN 
PMIEXLD Utility 167,205 — 
PMIFILET. See File Table. 
PMIFINDB search routine 105,107,209 


109... 
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PMIRCEND. See Output Format Table. 

PMIRCNTB. See Output Format Table. 

PMIRPTAB. See Company/Report/ 
‘Terminal Table. 

PMISNAP macro 112,116 

PMISPA medule (Release 8 only) 18 

PMISTATB. See Station Table. 

PMISTOP DD statement: 131 

PMISTOP macro 206 

PMITEST module 167,168 


PMIVERBS. See Edit Control Table. 


PMIWTO macro 112,116 
PMIWTOR macro 112,117 
PTRNTBLE. See Pattern Table. 
PUT service routine 
--calling format 60 , 62 
--and exclusive control 59 
--function 51 
--and indexed sequential 
files 62-63 
--and sequential access 
files 60-61 
--and SPAEXT VCONs 210 
--and subsystem processing 52 
--and ISAM/VSAM 
compatibility 70,74 
PUTV service routine 
--calling format 67-68 ,72 
--and exclusive control 70 
--and FHCW reason codes 70 
--function S51 
--and SPAEXT VCONs 210 
--and subsystem processing 52 
--and VSAM files 67-68 
--and VSAM processing 
options 69-70 


QBUILD function 87,110.3,210 


QCLOSE function 87,110.3,210 
QISAM access method 
--and exclusive control 57-59 


--and File Handler service 


routines 51-52 ,62 
--and ISAM/VSAM compatibility 74 
--return codes 63 
QOPEN function 87,110.3,210 
QPR. See MSGHQPR. 
QREAD function 87,110.3,210 
QREADX function 87,110.3,210 
QWRITE function 87,110.3,210 
QWRITEX function 87,110.3,210 
QSAM access method 51-52,57,60 
Queues 

--defined 15 
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--and Dynamic Data queuing 86-87 
--and Front End 11 
--illustrated 23,25 
--and INTERLOG 26 
--and Message Collection 96 
--and message switching 46.1 
--and TP interface 12 
--types of DDQs 86 
RBA. See Relative byte address. 
RBN. See Relative block number. 
RDW. See Record Descriptor Word. 
READ service routine 
--calling format 60,62,64 
--and direct access files 64-66 
--and exclusive control 57-59 
--function 51 
--and indexed sequential 
files 62-63 
--and ISAM/VSAM 
compatibility 70,74 
--and sequential access 
files 60-61 
--and SPA VCONs 209 
--and subsystem processing 52 
READONLY option 51,71 
Reason codes, VSAM 70,73 
Record Descriptor Word 61 
Reentrant subsystems 
--environment 33 
--example 46 
--and File Handler service 
routines 53-54 
--and LANG parameter (SYCTTBL 
macro) 18 
--and Message Collection 96 
--and MNCL parameter (SYCTTBL 
macro) 19,131,168 
--and MVS/XA loading 46.3 
--structure 31-32 
--vs. nonreentrant subsystems 16 
REENTSBS table 
--creation of 206 
--and MODCNTRL macro 113,116 
--and MVS/XA loading 46.2,116 
--and user subroutines 46.3,215 
--and USRSUBS 130,132 
REGA macro 112 
REGS macro 112 
Relative block number 54 , 64-66 
--example 123 
Relative byte address 54 ,67-69 
Relative record data set 54,67 
Relative record number 54,67-70 


Relative track and record 


number 54 
RELEASE service routine 
--calling format 56 
--and exclusive control 59 
--function 51 
--return codes 56 
--and SPA VCONs 209 
--and subsystem processing 52-53 
--use of 56-57 
--and VSAM 67,74 
RELEX service routine 59,210 
REPORT macro 206 
REPTAPE. See Batch Report Table. 
Residency 11,92,215 
RESOURC parameter (SYCTTBL 
macro) 19 
Resource Audit and Purge 116 
RESOURCE macro 19 
Resource Manager 12 
--and CATCH macro 114 
RESTART parameter (SYCTTBL macro) 46.1 
Restart/recovery 21,26,46.1 
Restarted messages 46.1 
Retriever 29 
\ Return codes 
--from Binary Search 105 
--from CONVERSE 91 
--from Edit Utility 49 
--from FECM calls 100 
--from FESEND 99 
--from File Handler 
- -BDAM 66 
-- ISAM 63 
--outline 55 
- -RELEX 59 
- -SELECT/RELEASE 56 
--sequential access 60 
-- VSAM 69-70,73 
--from Front End Control 
Message facility 100 
--from GETSEG 108 
--from INTSORT 110.2 
--from LOGPUT 97 
--from Message Collection 96 
--from queuing routine 44 
--from PMIDLTDB 107 
--from PMIFINDB 106 
--from STORAGE macro 41 
--from subroutine 100,123 
--from subsystem 22,31 
--illustrated 46 
--listed 34 
RETURN macro (IBM) 
--and nonreentrant subsystems 215 
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REUSE parameter (SYCTTBL macro) 46.2 
RLSE command 103 . 
RMODE linkedit parameter 46.2,197: 
ROUND macro 41,112 
RRDS. See Relative record data set. 


RRN. See Relative record number. 
RTNLINK macro 


76° 


--and coding techniques 42-43 
--and dynamic storage 40 
--and File Handler 52 - 
--and MVS/XA loading 46.2. 
--and nonreentrant subsystems *215-- 
--and output message area “* . 42,98 : 
--and SUBLINK macro . 112. . 
--and subsystem linkage ; 38" 
SAM. See System Accounting and 

Measurement. ae 
SAM parameter (SYCTTBL macro) + 117 
Sample subroutine (SQASMB) 123,125-127 
Sample subsystems 123,167 
Save area 215,217 
SAVE macro (IBM) 

--and nonreentrant subsystems 215 

SBA sequence (IBM 3270) 21,27,49 
SBSP parameter (SYCTTBL macro) 18,46.2 
SCT. See Subsystm Control Table. 
SCT Extension 200 
SCTEXTLT Dsect label .209 
SCTL command 110.3 
SCTLIST Dsect 40,200 
SCTLISTC copy member 200 
SECTEST macro (ESS) 112 
SECUSER routine (ESS) 15,110.3,210 
Segmented messages 

--and DDQ 15,30 

--input (GETSEG) 108 

--and MSGHQPR 22 

--output (DVASN) 109 

--and Output Utility 
SELECT service routine 

--calling format 56 

--function 51 

--and ISAM/VSAM compatibility 74 

--return codes 56 

--and SPA VCONs 209 

--and subsystem processing 52-53 

--use of 56 

--and VSAM . 
Share options (VSAM) 70-71 
SIMCRTA utility 


168 | 
Simulation Mode a ea 
123,129-131 -; 


--and BTAM simulator 
--execution JCL 138 
--imput messages 134-135 
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--linkedit JCL 136-137 
--linkedit JCL 136-137 


-- logging 27 

~-output from 
SIM3270 module 

--printout from 
Single-thread 


129,131 
131,139-158 


‘processing 4,131,168,215 
SNA 99 
Sriap 51 99 
Snap, issue 112 
Snaps, Test Mode 168 ,18&7-190 
Sort Facility . 110.2 
SPA. See System Parameter List. 
SPAEXT. See System Parameter List. 
SPALIST Dsect 40,200 
SPALIST macro 17 ,46,200, 206 
SSCONV macro 112 
SSSTART macro 46.3,112 
SSSTOP macro 46.3,112 
SSTEST macro 46.3,112 
STATION macro 206 
Station Table 17,98, 206-207 
Statistics 5,26 
STEPCAT DD statement (VSAM) 131 
STORAGE macro 

--and coding techniques 42,43 

--and DISPATCH macro 119 

-»and dynamic storage 49 

--and function 39 

--and input message area 42 

--and MVS/XA restrictions 46.2 

--and nonreentrant subsystems 215 

--and output message area 41,98 


--and output message length 41 


--and PASS macro 116,120 
STORE function 84-35 
Store/Fetch facility 

--and conversational subsystems L 

--and CONVERSE 88 

--function 15 

--service routines 110.3,210 

--and SPAEXT VCONs 210 

--and subsystem testing 130 

--use of 30,84-85 
STORFREE macro 

--and coding techniques 42-43 

--and DISPATCH macro 119 


--and function 39 


--and INTLOAD 46.2 
--and MVS/XA loading 46.2 
--and nonreentrant subsystems 215 
--and output message area 41-42 ,98 
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STRT command 139-140 
SUBLINK macro 112 
--and MVS/XA loading 46.2-46.3,110.4 
SUBMODS macro 46.2,130, 206 
Subroutines 
--calling of 10 
--and dynamic linkedit 30 
--and INTLOAD 46.2 
--and MODCNIRL macro 46.3,116,121 
--and MVS/XA loading 46.2-46.3 
--sample 125-127 
Subsystems 
- -coding 38-46.1 
--conversational 
--and CONVERSE 88-92 
--design considerations 93-94 
--and Dynamic Data Queuing 86-87 
--general concepts 79-80 


--implementation 81 


--and Store/Fetch 84-85 
--and USERSPA 82-83 
--defined 9-10 
--and dynamic linkedit 30 
--entry (Csect or ENTRY name) 39 
--and File Handler 52-55 
--illustration of 44-46 
--Intercomm-supplied 16 
--and INTLOAD 46.2,197 
--and message processing 35-38 
--and message switching 46.1,96 
--and MVS/XA 45 
--requirements and restrictions 46.2 
--nonreentrant 16 ,215-217 
--and output messages 98 
--reentrant 16,31-33 
--return codes from 34 
--sample inquiry 123,167 
--structure 31-32 
--testing 123 ,129-196 
--time controlled processing 30 
See also Reentrant subsystems. 
Subsystem Control Table (SCT) 
--creation of 18,206 
--Dsect generation 40,200 
--function 17-18 
--and message collection 96 
--and message flow using EDIT 
and OUTPUT 24 
--and message flow using MMU 22 
--and RESOURCE macro 19 
--and subsystem entry point 39,44 
--and subsystem structure 31-32 
--and subsystem testing 130,167 


See 
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Subsystem Controller 
--function 12 
--and File Handler return codes 55 
--and INTERLOG 28-29 
--and message processing 
concepts 35 
--and return codes 42 
--and subsystem structure 31-34 
SUBTASK macro 46.2,113,117,215 
SWMODE interface routine 46.3 
SYCTTBL macro 
--BLDL parameter 46.2 
--and Front End Queue Table 205 
--function 17 
--and INTSCT 130,132 ,167,180 
--LANG parameter 18 ,46.2,215 
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